CLI reference

Available Limited beta

Two operator binaries ship inside the control-plane container image, and you run them through docker exec next to the daemon.

Back to Developers

Today the CLI surface is operator-oriented. It runs next to the daemon, not on a laptop.

A tenant-facing CLI is in development and is described at the end of this page.

  • Available 5 items Works today in the private beta.
  • In development 1 item Being built. Not callable yet.

Running the binaries

What an import run does

An import is a single transaction-bounded run, not a stream of writes. It refuses a database role that is too privileged, holds a lock for the tenant, and records every site before it loads anything, so a failure can tell you which site stopped it and nothing is half committed.

A DCIM import run

Six stages. The last one is planned, which is why imported sites do not appear in topology queries.

  1. Wired

    You point the importer at a bundle of site data and name the tenant it belongs to.

    • otimport load
  2. Wired

    The run refuses to start as a database superuser, or as any role that can bypass row-level security. The import is held to the same tenant isolation as everything else.

    • exit 2 if too privileged
  3. Wired

    It takes a lock for that tenant, so two imports for the same tenant cannot interleave. If the lock is held, the run stops and names the holder.

    • exit 6 if held
  4. Wired

    Each site is registered before any data lands, so a failure can say exactly which site stopped it.

    • running
    • loading
  5. Wired

    Create-only inserts land in one transaction per site. The site is then marked committed, with its projection still pending.

    • committed
    • projection: pending
  6. Planned

    Nothing reads that pending state yet, so imported data does not reach the graph. This is the gap, and it is why topology queries will not see imported sites.

Commands

otimport

Available

Loads a bundle of DCIM site data under one tenant.

The bundle is a directory of site data. otimport reads it and loads every site under the tenant you name.

Inserts are create-only. The importer does not update existing rows, so a second run over the same data adds nothing it could overwrite.

When the run ends, otimport writes a report to the report directory.

Usage bash
otimport load --tenant <TENANT> --bundle <DIR> --report-dir <DIR>

Options

  • --tenant string required

    The tenant that owns every row the import creates.

  • --bundle directory required

    Directory containing the bundle of site data to load.

  • --report-dir directory required

    Directory where the import report is written.

Behavior

  • One import per tenant at a time

    otimport takes a per-tenant advisory lock for the whole run. If another import holds the lock, otimport exits with code 6 and names the holder.

    Why Two imports for one tenant that interleave could each see half of the other's rows. A lock makes the second run wait for a clear answer instead of producing a mixed result.

  • Refuses a privileged database role

    otimport will not run as a database superuser or as any role that bypasses row-level security. It exits with code 2.

    Why The import is deliberately subject to the same tenant isolation as every other write. A role that bypasses row-level security would make the importer the one component that could write across tenants.

  • Per-site row ceiling

    otimport enforces a ceiling on rows per site and refuses an oversized site before it loads anything from it.

    Why Rejecting up front is cheaper and safer than discovering the limit halfway through a transaction.

  • First failure stops the run

    The run stops at the first failure and records which site failed. Sites that were partially loaded are not committed.

    Why A half-loaded site is harder to reason about than a missing one. Stopping early keeps the committed data a set of complete sites.

States

Import run and per-site record states
StateMeaning
runningThe import run has started and is working through the bundle.
loadingA site is being loaded.
finishedThe site has loaded without error and is waiting to be committed.
committedThe site's rows are durable.
failedThe run or site failed. The record names the site that stopped the run.

Exit codes

otimport exit codes
CodeMeaningWhat to do
0Success.Nothing. The report is in the report directory.
2Refused: the database role is too privileged.Run with a role that is not a superuser and does not bypass row-level security.
6Another import holds the tenant lock.Read the holder named in the output. Wait for that import to end, then run again.
Other nonzeroA failure.The report describes the failure and names the site that stopped the run.

Examples

Load a bundle under one tenant bash, illustrative
docker exec <control-plane-container> \
  otimport load \
    --tenant <TENANT> \
    --bundle /path/inside/container/bundle \
    --report-dir /path/inside/container/reports
Illustrative. Both directories are paths inside the container, so mount them first.

otctl

Available

Operator CLI. Administers webhook signing keys and API keys.

otctl webhook-key manages the HMAC signing keys used by the DHCP lease webhook. You create a key for a tenant, list the keys that exist, and revoke a key you no longer trust.

otctl api-key administers the API keys that callers present to the platform. It is the other command surface available today.

Creating a tenant is not available through the CLI. Tenant provisioning has no code path yet and is handled by hand during the private beta.

Usage bash
otctl <webhook-key|api-key> <subcommand>

Subcommands

  • otctl <webhook-key|api-key> create Available

    Create a signing key for a tenant.

  • otctl <webhook-key|api-key> list Available

    List signing keys.

  • otctl <webhook-key|api-key> revoke Available

    Revoke a signing key so it stops verifying.

Behavior

  • Operator credential required

    otctl needs an operator credential. It is separate from the tenant API keys used to call the gRPC API.

    Why Tenant credentials act inside one tenant. Administering the keys that authenticate ingestion is an operator task, so it does not share a credential with the tenant calls it protects.

  • Keys are rotatable

    Each webhook request carries a key id, so you can create a new key, move senders over, and revoke the old one without a flag day.

Examples

Manage signing keys bash, illustrative
docker exec <control-plane-container> otctl webhook-key create --tenant <TENANT>
docker exec <control-plane-container> otctl webhook-key list
docker exec <control-plane-container> otctl webhook-key revoke <KEY_ID>
Illustrative. Subcommand and flag names are illustrative and may change during the beta.

In development

Tenant-facing CLI

In development

A CLI you would run from a workstation rather than next to the daemon. It is being built and is not available yet.

Planned capabilities

  • Login with a tenant credential.
  • Prefix allocation.
  • Lease inspection.

Get beta access

The CLI is part of the limited beta.

Join the beta