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. |
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
Related#
- Set up the CLI — login and environment defaults
- REST API — the surface underneath
- Platform tools — the same operations over MCP