Skip to content

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

On Windows, in PowerShell:

irm https://agents.example.com/install.ps1 | iex

--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 of the current server. --all logs out of every server.
auth status Who you are signed in as, token validity, and the other servers you are logged in to.

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.

context#

Command Does
use Save <org> or <org>/<project> as the context that commands use when they name none. @<server> changes to another server you are logged in to, by its URL, host and port, or host; --clear forgets the saved context.
context Show the current context and where it comes from.
context list List the orgs and projects you can use, and mark the current one.

See Context for which source wins.

installation#

Command Does
installation status Whether this install is activated, and whether people can sign in.
installation activate Activate the install with --code, --name, --company, and --email. It then runs in evaluation mode.
installation use-lens-id Use Lens ID for sign-in, approved in Lens Cloud with a device code. Needs --code.
installation license Show the license. With a key and --owner, enter the key that ends the evaluation; that needs an installation owner.

See Activation and license.


sandbox#

The main event. See Sandboxes.

A command that takes a sandbox finds it by slug, ID, or name. A slug or ID that matches wins. A name is used only when one sandbox has it; a name that several sandboxes have stops the command with a list of their slugs.

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. --auto-stop, --auto-delete, and --auto-start set its timers. --user and --workdir set who the agent runs as and where. --volume PATH[:SIZE], such as /data:20Gi, adds a persistent volume. --port name=NAME,port=PORT,auth=private\|public\|webhook publishes a port; a webhook port also takes scheme=, header=, prefix=, algorithm=, encoding=, and signed-url=, and its secret comes from --webhook-secret-file NAME=PATH.
sandbox list List sandboxes in a project, or with --org in every project of an org. With no project from a flag, an env var, or the context, or with -A, it lists every project you can see.
sandbox get Show one by slug, id, or name.
sandbox describe Detailed multi-section view — configuration, state, health, ports, policies.
sandbox update Change configuration. Image, command, env, CPU, memory, port, health-check, --user, or --workdir changes create a revision and restart; --clear-user goes back to the image's USER, and --clear-workdir to WORKSPACE_PATH from the env, else the image's WORKDIR. --auto-stop, --auto-delete, --auto-start, and their --clear- forms change the timers without a restart. -f with a larger volumes[].size grows the volume without a restart. --webhook-secret-file sets the secret of a webhook port in the same update.
sandbox export Print as a spec, ready to re-apply. Credential values and webhook secrets are omitted.
sandbox webhook-secret Set or rotate the secret of a webhook exposed port, from stdin or --from-file, without a restart. Needs the project ADMIN role.
sandbox start / stop Idempotent lifecycle control.
sandbox delete Delete. Cleanup is asynchronous.
sandbox logs Print the container's output, kubectl logs style. -f follows it; --tail <n>, 1 to 10000, sets how many lines to start with (500 by default). See Logs.
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 run Create a sandbox, run one command, and exit with its code. Takes the create spec flags; --rm deletes it afterwards.
sandbox cp Copy files to or from a sandbox, <sandbox>:<path> on one side. Needs tar on both ends.
sandbox set-limit Per-sandbox LLM budget cap.
sandbox spend LLM spend attributed to this sandbox.
sandbox port-forward Forward a local port to a port on the sandbox's loopback: LOCAL:REMOTE, or one number for both. Listens on 127.0.0.1. --stdio carries one connection for an OpenSSH ProxyCommand. Needs the project ADMIN role.
sandbox ssh-config Print a ~/.ssh/config entry that reaches every sandbox of a --project, or of every project of an --org, as <sandbox>.<project>.<org>.nexus.
sandbox ssh-proxy The ProxyCommand that entry runs: SSH on stdin and stdout, one exec for each shell, command, or sftp session, with no sshd in the sandbox. Needs the project ADMIN role.

Revisions and rollback, restart, and taking an image update are REST and MCP surfaces; there is no CLI verb for them.

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.

integration#

Kubernetes clusters and AWS connections, which a policy grants to sandboxes as its integrations. Every command works in one project, from --project or the context. See Kubernetes and AWS.

Command Does
integration list Both kinds in one table. -o name prints integration/<type>/<name>.
integration kubernetes list / get List or show clusters. k8s is an alias for kubernetes.
integration kubernetes create --relay-url tunnel:// for a reverse tunnel, or a relay endpoint.
integration kubernetes update Display name, description, relay, CA certificate.
integration kubernetes delete Delete a cluster.
integration kubernetes rotate-tunnel-token New token, printed once and never stored.
integration aws list / get List or show connections.
integration aws create --secret-access-key-stdin preferred. Role ARN, external id, and region required.
integration aws update Change settings.
integration aws 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.

project member#

Command Does
project member list Users and API tokens with a role on a project.
project member set Give a role, or change it. --user <oidc-subject\|email> or --api-token <name\|id>, and --role ADMIN\|MEMBER (default MEMBER). Requires org admin.
project member remove Remove a user's or API token's role. --user or --api-token. Requires org admin.

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.

workload-identity#

See Workload identity federation.

Command Does
workload-identity issuer list Trusted issuers of an organization, and the audience to use for it.
workload-identity issuer add Trust an issuer. --preset github\|gitlab\|buildkite\|google-cloud\|kubernetes fills in its URL and the claims every rule must pin; --issuer, --audience, --jwks-uri or --jwks-file, and --required-claim set them yourself. Without a preset, --name, --issuer, and at least one --required-claim are required. --preset kubernetes also needs --issuer.
workload-identity issuer remove Stop trusting an issuer, by name, URL, or id. Its rules and their sessions go with it.
workload-identity token Exchange this workload's OIDC token for a short-lived API token, printed to stdout. --federated-token (or NEXUS_FEDERATED_TOKEN) is the ID of the federated token to act as; --audience asks the GitHub Actions runner for the OIDC token, --token-file reads it from a file.
workload-identity explain What a workload token in --token-file would resolve to in a project. Grants nothing.

federated-token#

Command Does
federated-token list Federated tokens of a project.
federated-token create Create one with --name and --role (MEMBER by default). It has no secret.
federated-token delete Revoke one. Its sessions stop at once.
federated-token rule list Rules of a federated token.
federated-token rule add Let workload tokens from --issuer whose claims all match act as it. Repeat --claim key=value.
federated-token rule remove Remove a rule by id. Its sessions stop at once.

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\|project\|user\|agent\|sandbox, --period day\|week\|month, --limit-cents, and --anchor to renew from a chosen whole UTC hour. Without --anchor, the period is a calendar period.
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