Command-line interface

Configure Infra CLI contexts and inspect or change infrastructure from a terminal.

The infra CLI uses the same authorization, revisions, and asynchronous operations as the HTTP API. Install the signed package for your platform from the console's Settings → Developer tools page.

Configure a contextCopy link

A context records an API base URL, organization ID, and optional project ID. Authentication can use an interactive session or a service-account token supplied through the environment. On your administrative workstation, create a context:

infra context create production \
  --api-url https://infra.example.com/api/v1 \
  --organization ORGANIZATION_ID \
  --project PROJECT_ID

Replace the following:

• ORGANIZATION_ID: the organization ID shown in its settings.
• PROJECT_ID: the project ID shown in its settings.

Replace https://infra.example.com/api/v1 with the installation's API base URL. To select the context for subsequent commands, run:

infra context use production

Authenticate through the selected control plane:

infra login

Interactive login opens the configured control-plane authentication flow. For automation, supply INFRA_API_TOKEN from a secret store instead of invoking login. A context does not grant permissions that the authenticated account lacks.

Context precedenceCopy link

Explicit command flags override INFRA_API_URL, INFRA_ORGANIZATION, and INFRA_PROJECT; environment values override the active context. INFRA_API_TOKEN overrides an interactive stored credential for that invocation.

Check infra context show before a mutation. The CLI prints the selected organization and project in an interactive impact review. Non-interactive scripts must supply the intended scope explicitly or use a dedicated context.

Inspect resourcesCopy link

To list the active project's droplets labeled service=web, run:

infra droplets list --label service=web

To read one droplet as JSON, run:

infra droplets get DROPLET_ID --output json

Replace DROPLET_ID with an ID returned by the list command. To inspect an accepted change, run:

infra operations get OPERATION_ID

Replace OPERATION_ID with the operation ID returned by the change request. To list fleet nodes in a region, run:

infra nodes list --region REGION_ID

Replace REGION_ID with the region ID shown in Fleet → Regions. This command requires fleet-read access to that region.

--output json emits the documented API envelope without the human table. Parse IDs and fields in scripts rather than column positions or translated messages. Unknown flags and invalid values produce a nonzero exit status before a request is sent.

Create and waitCopy link

Save a droplet request as droplet.json, then submit it from the directory containing the file with an explicit idempotency key:

infra droplets create --file droplet.json \
  --idempotency-key payments-web-01-create-v1 --wait --timeout 15m

Without --wait, an accepted asynchronous request prints its operation ID and exits successfully after acceptance. With --wait, the CLI polls until a terminal state or the timeout. A timeout stops polling but leaves the server operation running. Read the printed operation ID before retrying.

Exit statusesCopy link

The exit status distinguishes request rejection from a local wait deadline:

Press Ctrl-C to stop the local command. It does not cancel server work. To request cancellation, run infra operations cancel OPERATION_ID with the operation ID printed by the original command. Cancellation requires cancelable=true; follow Cancellation for the terminal result and completed work that remains.

Changes and deletionCopy link

The CLI reads current revisions before ordinary interactive configuration updates. Scripts can pass --if-match to apply an explicitly reviewed revision. A stale revision fails rather than overwriting concurrent changes.

Deletion requires an interactive confirmation or --yes in an intentional script. Resource-side deletion protection and permission checks still apply. Prefer blueprints for reviewed changes spanning several resources.