CLI reference#

nexusctl is organised like kubectl: nexusctl <resource> <verb>. Global flags work everywhere.

Global flag	Purpose
`--server <url>`	Platform URL. Overrides `NEXUS_URL` and the stored credentials.
`-o, --output <format>`	`table` (default), `json`, or `yaml`.
`-h, --help`	Help at any level.

Environment defaults: NEXUS_URL, NEXUS_ORG, NEXUS_PROJECT. See Set up the CLI.

Install it from your own platform, which serves a build matching its version:

curl -fsSL https://agents.example.com/install.sh | sh

--help on the version you have installed is authoritative. This page is the map.

auth#

Command	Does
`auth login`	Browser sign-in. Credentials are stored under `~/.nexus/`, beside the server URL the installer wrote there.
`auth logout`	Log out and delete stored credentials.
`auth status`	Who you are signed in as, and token validity.

A valid sign-in can still be refused with 403 where the installation names owners and you belong to no organization, may not create one, and hold no invitation.

installation#

Command	Does
`installation status`	Whether this install is activated.
`installation activate`	Activate against Lens Cloud via the device flow. See Activation.

sandbox#

The main event. See Sandboxes.

Command	Does
`sandbox init`	Write a commented example spec to stdout, or a file with `--out`.
`sandbox create`	Create and start a sandbox. `-f` for a spec file.
`sandbox list`	List sandboxes in a project.
`sandbox get`	Show one by slug or id.
`sandbox describe`	Detailed multi-section view — configuration, state, health, ports, policies.
`sandbox update`	Change configuration. Image, command, env, or port changes create a revision and restart.
`sandbox export`	Print as a spec, ready to re-apply. Credential values are omitted.
`sandbox start` / `stop`	Idempotent lifecycle control.
`sandbox delete`	Delete. Cleanup is asynchronous.
`sandbox exec`	Run a command inside, kubectl-exec style. `-i` for stdin, `-t` for a TTY.
`sandbox shell`	Interactive shell. Sugar for `exec -it -- bash`; `--shell` to change it.
`sandbox set-limit`	Per-sandbox LLM budget cap.
`sandbox spend`	LLM spend attributed to this sandbox.

Revisions and rollback are REST and MCP surfaces; there is no CLI verb for them.

shell#

Command	Does
`shell exec`	One-shot command in the project's shell sandbox. `--workdir`, `--timeout`.

For interactive access to an agent sandbox, use sandbox shell. See Exec and shell.

policy#

See Policies.

Command	Does
`policy list`	List policies in a project or org.
`policy get`	Show one by name or id.
`policy describe`	Allowed domains, connectors, credentials, integrations, PII masking, and bindings in one view. Each domain row carries every fence on the entry — scheme, transport, caller binaries, and HTTP rules.
`policy create`	From a YAML or JSON body. `-f -` reads stdin.
`policy update`	Each top-level field supplied replaces the existing value.
`policy delete`	Delete a policy.

In policy describe output, a domain row reads pattern, verdict, scheme/transport, callers=, rules=. any means the policy omits that key; on a caller fence none means it carries an empty list, so nothing passes. A deny row prints - for transport. See Reading fences from the CLI.

policy-binding#

See Policy bindings.

Command	Does
`policy-binding list`	List bindings in a project or org.
`policy-binding get`	Show one by id.
`policy-binding describe`	Policy names and subjects rendered for humans.
`policy-binding create`	Attach policies to subjects. `--position` sets merge order.
`policy-binding update`	Change mutable fields. `--clear-description` blanks the description.
`policy-binding delete`	Delete a binding.
`policy-binding list-drift`	Project bindings clipped by the org policy ceiling.

credential#

See Credentials.

Command	Does
`credential list`	List credentials. Values are never returned.
`credential get`	Show one by name or id.
`credential create`	`--value-stdin` preferred over `--value`. `--inject` is repeatable.
`credential update`	Change name, value, or injections.
`credential delete`	Delete the credential and its injections.

connector#

See MCP connectors.

Command	Does
`connector list`	List connectors in a project.
`connector get`	Show a connector and its discovered tools.
`connector describe`	Identity, status, transport, tools, and credentials in one view.
`connector create`	`--transport sse\\|streamable-http`, `--cluster`, `--defer-discovery`.
`connector update`	Change mutable fields.
`connector delete`	Delete a connector.
`connector sync`	Re-probe the upstream and refresh the tool list.

cluster#

See Kubernetes.

Command	Does
`cluster list` / `get`	List or show clusters.
`cluster create`	`--relay-url tunnel://` for a reverse tunnel, or a relay endpoint.
`cluster update`	Display name, description, relay, CA certificate.
`cluster delete`	Delete a cluster.
`cluster rotate-tunnel-token`	New token, printed once and never stored.

aws-connection#

See AWS.

Command	Does
`aws-connection list` / `get`	List or show connections.
`aws-connection create`	`--secret-access-key-stdin` preferred. Role ARN, external id, and region required.
`aws-connection update`	Change settings.
`aws-connection delete`	Delete a connection.

org#

Command	Does
`org list` / `get`	Organizations you can access.
`org create`	`--name` slug, `--display-name`. Refused with `403` on an installation that names owners, unless you are one.
`org update`	Rename the display name.
`org delete`	Delete an organization.

Where config.ownerEmails is set, only those addresses may create an organization and everybody else joins one by invitation. See Installation owners.

project#

Command	Does
`project list` / `get`	Projects in an organization.
`project describe`	Clusters, policies, AWS connections, and resource counts.
`project create`	`--name` slug, `--display-name`.
`project update` / `delete`	Change or remove a project.

team#

Command	Does
`team list` / `get`	Teams in an organization.
`team create` / `update` / `delete`	Manage teams.
`team add-member`	`--user <oidc-subject>` or `--api-token <name\\|uuid>`.
`team remove-member`	By membership UUID from `team get`.
`team set-access`	Grant a project role: `ADMIN` or `MEMBER`.
`team remove-access`	Revoke project access.

invitation#

Command	Does
`invitation create`	Invite by email with a role.
`invitation list`	Invitations your org issued. Requires org admin.
`invitation revoke`	Revoke a pending invitation by UUID.
`invitation list-mine`	Invitations pending for you.
`invitation accept` / `decline`	Act on your own invitations.

api-token#

See API tokens.

Command	Does
`api-token list`	Tokens in an organization.
`api-token create`	The secret is printed once. `--expires-in-days` for a lifetime.
`api-token revoke`	By id or name. Name lookup needs `--org`.

spending-limit#

See Spending limits.

Command	Does
`spending-limit list`	Limits for an organization.
`spending-limit status`	Limit, spend, and remaining for each.
`spending-limit set`	`--actor-type org\\|user\\|agent\\|sandbox`, `--period day\\|week\\|month`, `--limit-cents`.
`spending-limit delete`	Delete a limit by id.

Recipes#

# Copy a policy between projects
nexusctl policy get agent-base -o yaml | nexusctl policy create --project staging -f -

# Promote a sandbox from staging to production
nexusctl sandbox export nightly-refactor --project staging \
  | nexusctl sandbox create --project production -f -

# Find broken sandboxes
nexusctl sandbox list --project production -o json \
  | jq -r '.[] | select(.state=="error") | "\(.slug)\t\(.errorReason)"'

# Audit the org ceiling
nexusctl policy-binding list-drift --org acme

Set up the CLI — login and environment defaults
REST API — the surface underneath
Platform tools — the same operations over MCP