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, installed from your own server in one command below.

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. A few operations show no Agent tab because no MCP tool backs them — activation, sandbox exec, and sandbox export.

Install#

Your own server serves the CLI. Point the installer at the platform URL:

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

That command downloads the binary, verifies it against the checksum the server published, installs it, and writes ~/.nexus/config.json pointing at that server. It ends by telling you to run nexusctl auth login.

The binary matches the server. The installer is rendered per request with the URL and version of the server serving it, so the CLI you get is built for the platform you are going to talk to. Upgrade the platform, run the same command again, and the client moves with it.

The download is checksum-verified. The installer fetches SHA256SUMS alongside the binary and compares the two before installing anything. A mismatch aborts rather than installs.

No registry is involved. The binaries are baked into the platform image and served from the server itself, so an air-gapped install needs no package registry and no outbound access to one.

/install.sh and the /cli/ downloads are unauthenticated by necessity: you have no credentials until the CLI that obtains them exists.

What it needs and where it lands#

Detail Value
Requires curl, gzip, and sha256sum or shasum
Detects Linux and macOS, on x86-64 and arm64
Install directory $HOME/.local/bin, or $NEXUSCTL_INSTALL_DIR if you set it
Writes $HOME/.nexus/config.json, holding the server URL

The installer refuses rather than guesses on an operating system or architecture it does not recognize, naming what it found. Where your platform is recognized but the server carries no build for it, the download fails saying so.

Set NEXUSCTL_INSTALL_DIR to install somewhere already on your PATH:

curl -fsSL https://agents.example.com/install.sh \
  | NEXUSCTL_INSTALL_DIR=/usr/local/bin sh

The installer tells you if the install directory is not on your PATH.

Read it before you pipe it

curl -fsSL https://agents.example.com/install.sh prints the script instead of running it. It is short, and the whole of its work happens in a main function called on the last line — so a dropped connection cannot leave a truncated prefix half-executed.

Point it at your platform#

The installer already set the server, so no command needs --server. Two more environment variables remove the rest of the repetition:

export NEXUS_ORG=acme
export NEXUS_PROJECT=production
Variable Replaces Notes
NEXUS_URL --server Set by the installer in ~/.nexus/config.json; export it only to override that.
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 ~/.nexus/config.json. To work against a second installation, export NEXUS_URL for that shell or pass --server per command — re-running install.sh would repoint the config file for every shell.

Log in#

nexusctl auth login

The command opens your browser, you sign in with your identity provider, and the credentials are saved under ~/.nexus/ beside the server URL the installer wrote there.

Where your installation names owners, a successful sign-in can still be refused with 403 — the token is valid, but the person belongs to no organization, may not create one, and holds no pending invitation.

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

policy describe renders every fence on an allowed domain — scheme, transport, caller binaries, and HTTP rules — so a restriction is auditable from the terminal. See Reading fences from the CLI.

Distributing the CLI through your own internal channels, or to an air-gapped estate, is worth a conversation. Talk to us.