Skip to content

Set up the CLI#

nexusctl is the command-line client for a Lens Agents installation. It is organised like kubectl: nexusctl <resource> <verb>, with -o table|json|yaml on every command.

Everything the CLI does, the REST API does too — the CLI is a client of it, and so is the MCP endpoint.

Hands-on pages in these docs therefore show the same task up to three ways:

Tab What it is Needs
API A curl call, authenticated with an API token in $LENS_AGENTS_TOKEN. Nothing beyond curl.
Agent Plain English, typed at an AI tool connected to the MCP endpoint. An MCP client you probably already run.
CLI A nexusctl command. The binary, which ships with your deployment.

All three reach the same server under the same identity, RBAC, policies, and audit. API comes first because it works from any machine with curl and needs nothing installed; the CLI comes last because you need the binary in hand first. A few operations show no Agent tab because no MCP tool backs them — activation, sandbox exec, and sandbox export.

Getting the binary

nexusctl is distributed with your deployment rather than from a public download page. Talk to us to get the build for your platform. Until you have it, every example in these docs has a curl equivalent that works against any install.

Point it at your platform#

Three environment variables remove most repetition:

export NEXUS_URL=https://agents.example.com
export NEXUS_ORG=acme
export NEXUS_PROJECT=production
Variable Replaces Notes
NEXUS_URL --server Also read from the stored credentials file after login.
NEXUS_ORG --org Used by org-scoped commands: teams, API tokens, spending limits.
NEXUS_PROJECT --project Used by project-scoped commands: sandboxes, policies, credentials, connectors.

--server overrides NEXUS_URL, which overrides the credentials file.

Log in#

nexusctl auth login

The command opens your browser, you sign in with your identity provider, and the credentials are saved under ~/.nexus/.

Check who you are:

curl -fsS -H "Authorization: Bearer $LENS_AGENTS_TOKEN" \
  https://agents.example.com/v1/auth/me

nexusctl auth status

Log out and delete the stored credentials with nexusctl auth logout.

Non-interactive access#

CI jobs, scripts, and external agents cannot open a browser. They use an API token instead.

Create an API token called ci-deploy in the acme org, valid for 90 days.

nexusctl api-token create --org acme --name ci-deploy --expires-in-days 90

The secret is printed once. Capture it at creation time — the platform stores only a hash and cannot show it again.

Use it as a bearer token against the API:

curl -fsS -H "Authorization: Bearer $LENS_AGENTS_TOKEN" \
  https://agents.example.com/v1/orgs

An API token is its own principal in the identity model. It gets its own policy bindings, its own team memberships, and its own rows in the audit trail — actions taken with a token are never attributed to the person who created it.

Output formats#

table is the default and is meant for reading. json and yaml are meant for piping.

nexusctl sandbox list -o json | jq -r '.[] | select(.state=="error") | .slug'

yaml output round-trips into the matching create/update command, which is how you copy a resource between projects:

nexusctl policy get agent-base -o yaml \
  | nexusctl policy create --project staging -f -

Discovering commands#

--help works at every level and is the authoritative reference for the version you have installed.

nexusctl --help
nexusctl sandbox --help
nexusctl sandbox create --help

Several resources also have a describe verb that joins related records into one human-readable view, the way kubectl describe does:

nexusctl project describe production
nexusctl sandbox describe nightly-refactor
nexusctl policy describe agent-base
nexusctl connector describe github