Command line (msty-nexusctl)

msty-nexusctl manages Nexus from a terminal, a script or an AI agent. It uses the same API as the Console, with the same permissions and plan limits. Having it doesn’t unlock anything your plan doesn’t include.

Get it

msty-nexusctl comes with the Nexus Runtime. On a machine set up with Add a machine (see Fleet), it’s installed here:

System	Folder
macOS and Linux	~/.local/bin
Windows	%LOCALAPPDATA%\msty-nexus\bin

Sign in with a key

The CLI uses a Nexus key from Connections:

• An Inference only key for chat, embeddings and other model calls.
• An Administration key Pro for anything that changes Nexus: providers, models, keys, routes.

Give it the key in a file, so it doesn’t show up in your shell history or the process list:

msty-nexusctl --token-file ~/.config/nexus-admin-key health

Or set environment variables:

export MSTY_NEXUS_URL=http://127.0.0.1:3939
export MSTY_NEXUS_TOKEN=...   # your Nexus key
msty-nexusctl capabilities

Keep key files readable only by you (mode 0600 on macOS and Linux).

Global flags

Flag	What it does
--url <url>	The Nexus address. Default: MSTY_NEXUS_URL, or http://127.0.0.1:3939. Use 3949 for Business.
--token <key>	The Nexus key. Default: MSTY_NEXUS_TOKEN. Prefer --token-file.
--token-file <path>	Read the key from a private file. Can’t be used with --token.
--request-timeout <duration>	A total time limit for the command, such as 2m.
--output json	JSON output. This is the default.

Flags can go before or after the command.

Output and exit codes

• Success: JSON on stdout. Streaming commands print one JSON event per line.
• Failure: one JSON object on stderr, with the Nexus error code, HTTP status and request ID.
• Exit codes: 0 success, 1 the operation failed, 2 invalid arguments.

Long tasks, such as a model download, return as soon as Nexus accepts them. Add --wait (and --wait-timeout), or use jobs wait <id>, to wait until they finish.

Examples

Check health and what this Nexus supports:

msty-nexusctl health
msty-nexusctl doctor --provider-checks

Connect OpenAI, reading the key from stdin so it never appears in a command:

printf '%s\n' "$OPENAI_API_KEY" | msty-nexusctl providers set --id openai --name OpenAI --kind openai --credential-stdin
msty-nexusctl providers check openai
msty-nexusctl models sync --provider-id openai --wait --wait-timeout 2m

Download a local model and wait for it:

msty-nexusctl models search --query gemma --source huggingface,ollama
msty-nexusctl models pull gemma3 --service ollama --wait --wait-timeout 5m

Make an inference key for an app:

msty-nexusctl tokens create --name "Raycast" --role inference

Approve a paired app by the code it shows:

msty-nexusctl apps approve K7QM-4ZP2 --access inference,web,tools

Send a chat:

msty-nexusctl chat --model @route/everyday --message "Say hello." --stream

Commands

Status and setup

Command	What it does
health, version	Is the Runtime up, and which build
capabilities	What this Runtime supports
features status, features sync	Show this machine’s paid features, or fetch them again from your account
settings, settings set-cors --origins <csv>	Read settings; set allowed browser origins
hardware [show|refresh]	The machine’s CPU, GPU and memory
doctor [--provider-checks] [--cluster]	Run checks and report problems
admin-guard status|export	Your organization’s Guard policy on this machine

Records

Command	What it does
usage summary	Usage by date, provider, model or key
audit list	Admin changes, filtered by action, resource, actor or time
logs sources, logs read	Runtime and cluster-worker diagnostic logs
jobs list|get|watch|wait|cancel	Background tasks such as downloads and installs

Models and runtimes

Command	What it does
models list|get|set|delete	Model records
models search|pull|import|remove|sync	Find, download, import, remove and refresh models
models copy-offer, models copy	Copy a model to another machine
models placement get|set|plan|apply|rollback|state|effective	GPU and memory placement for a local model
models benchmark run|list|get|recommend	Benchmark a model
gpu qualify <id>	Check how a model runs on the GPU
services list|get|install|start|stop|restart|update|rollback|uninstall|enable|disable	Local runtimes such as MLX, llama.cpp and Ollama
services diagnostics|versions <id>	A runtime’s health and available versions
services accounts <id> [login|finish|enable|disable|remove]	Sign in to Claude, Codex or Antigravity subscriptions
runtime-discovery adopt	Add model servers found on this machine

Providers, keys and apps

Command	What it does
providers list|get|check|set|delete	Online and compatible providers
tokens list|get|create|update|rotate|delete	Client API keys: role, allowed models, labels
apps list|approve|deny|revoke|remove|invite	Connected apps; invite makes a connect link
pairing list|approve|deny	Desktop apps asking for access on this machine
presets list|get|set|delete	Presets
presets suggest	Suggest preset settings from a goal or a sample request

Serving

Command	What it does
routes list|get|set|validate|enable|disable|delete|status	Smart Routes
routes preview, routes dry-run	See where a request would go, without sending it
routes prepare [--backend mlx|llamacpp|ollama]	Set up the router model
routes export	Save a support file about your routes. It never holds message text or keys.
pools list|get|set|validate|delete	Smart Balancer pools
network status|watch|traces	Live balancer state and request traces
nodes list|get|join-command|join|preflight|probe|sync|drain|resume|remove|reset-join-tokens	Balancer nodes
cluster topology|members|add-member|remove-member|discover|configure-links|provision	Cluster setup
cluster join-command|join-token|reset-join-tokens	Add Macs to a cluster
cluster models|place|load|unload|prepare-model|form|leave	Run models across the cluster

Model calls

Command	What it does
chat	Chat completion
messages, messages count-tokens	Anthropic Messages
responses and responses input-tokens|compact|get|input-items|cancel|delete	Responses API
embeddings	Embeddings

Anything else: api

For any JSON route without its own command, call it directly:

msty-nexusctl api GET /v1/data-protection/status
msty-nexusctl api PATCH /v1/settings --input settings.json
msty-nexusctl api POST /v1/chat/completions --input - < request.json

• Methods: GET, POST, PUT, PATCH, DELETE.
• Paths must start with /v1/, or be /health or /version.
• --input - reads JSON from stdin, up to 16 MiB.
• It’s for JSON only: not uploads, downloads or event streams.

Errors to expect

Code	Means
UNAUTHORIZED	Wrong or missing key
FORBIDDEN	The key’s role can’t do this. Management needs an Administration key.
FEATURE_NOT_ENTITLED	Your plan or this machine doesn’t include it. Don’t retry another way.
CLIENT_TOKEN_LOCKED_BY_ENTITLEMENT	The key is over your plan’s limit and locked

More codes: Gateway API.