Set up the CLI#
nexusctl is the command-line client for a Mirantis Agent Platform 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 and sandbox export. sandbox exec, sandbox run, and sandbox cp are CLI-only: they run over the exec WebSocket, which has no MCP tool and no curl equivalent.
Install#
Your own server serves the CLI. Point the installer at the platform URL:
curl -fsSL https://agents.example.com/install.sh | sh
In PowerShell:
irm https://agents.example.com/install.ps1 | iex
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, /install.ps1, 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; on Windows, PowerShell |
| Detects | Linux on x86-64 and arm64, Apple Silicon macOS, and Windows on x86-64 (arm64 runs the x86-64 build) |
| Install directory | $HOME/.local/bin, or %LOCALAPPDATA%\Programs\nexusctl on Windows, or $NEXUSCTL_INSTALL_DIR if you set it |
| Writes | $HOME/.nexus/config.json, holding the server URL |
On Windows, the installer adds the install directory to your user PATH. Close every running nexusctl before you run it again: Windows locks a running executable. nexusctl sandbox cp uses the tar.exe that Windows 10 and later include.
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: projects, 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, log in to it with nexusctl auth login --server <url> and change between installations with nexusctl use @<server> (see Context), or export NEXUS_URL for one shell or pass --server per command — re-running install.sh would repoint the config file for every shell.
Context#
Instead of exporting variables, save the org and project once:
nexusctl use acme/production
nexusctl context
nexusctl context list
nexusctl context shows the current context and where it comes from, and nexusctl context list the orgs and projects you can use. For a project or org, the first source that is set wins:
--projector--orgNEXUS_PROJECTorNEXUS_ORGNEXUS_CONTEXT, for one shell- The nearest
.nexus.toml, withcontext = "acme/production", for one repository - The context
nexusctl usesaved for the server
A --project or --org you type wins over the other one's environment variable. When the context fills in a value, nexusctl writes the value and its source to stderr. A project name is unique only within its org, so name a project that is in more than one org as <org>/<project>.
With logins to more than one server, nexusctl use @agents.example.com changes to another server you are logged in to, and nexusctl use acme/production@agents.example.com also saves a context for it. nexusctl auth status lists the other servers.
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 of the current server with nexusctl auth logout, or of every server with nexusctl auth logout --all.
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 project roles, 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.
Related#
- CLI reference — every command, grouped by resource
- REST API — the surface the CLI is built on
- API tokens — non-interactive principals
- Sandboxes — the first thing worth running
Distributing the CLI through your own internal channels, or to an air-gapped estate, is worth a conversation. Talk to us.