nexus-cli

The native Rust CLI for managing Nexus workspaces locally.

nexus-cli handles project scaffolding, authentication, agentic file import, workspace management, environment preflight checks, and configuration management for multi-agent engineering workflows.

Installation

One-liner (recommended)

curl -fsSL https://nexus.gatewarden.eu/install.sh | bash

The installer detects your platform (macOS / Linux, x86_64 / aarch64), downloads the pre-built binary from GitHub Releases, and verifies its SHA-256 checksum. If no binary exists for your platform it falls back to cargo install --git.

From source

cargo install --git https://github.com/gwnexus/nexus-cli.git nexusctl

Requires Rust >= 1.85.

Pin a version

NEXUS_VERSION=v0.6.12 curl -fsSL https://nexus.gatewarden.eu/install.sh | bash

Quick start

nexus login              # Authenticate with the Nexus platform
nexus init               # Initialize a Nexus project workspace
nexus preflight          # Verify environment readiness
nexus pull               # Sync skills and agent files from the platform

Commands

Global flags

nexus run

nexus run is the recommended way to launch OpenCode outside of a devbox environment. It reads platform-managed plugin configuration from .nexus/env and project secrets from .env.nexus.local, injects the resolved vars into the child process environment, and exec-replaces itself with the target tool.

nexus run                          # inject env vars + exec opencode
nexus run --dry-run                # show resolved env without launching
nexus run --show-env               # print env block then launch
nexus run --no-db                  # skip af_export, use .nexus/env only
nexus run --tool cursor            # launch a different tool
nexus run -- --model anthropic/claude-opus-4  # pass args through

Options

The default tool is opencode. To change it globally, set run.default_tool in ~/.config/nexus/config.toml:

[run]
default_tool = "opencode"

Dry-run output

>> nexus run --dry-run
   Project: NEXUS-APP (fdc7a78c)
   Tool:    opencode

   Resolved env-vars (7 injected, 0 skipped — already in shell):
     HEADROOM_MODE                 = transform     [.nexus/env]
     HEADROOM_DEBUG                = false         [.nexus/env]
     HEADROOM_REQUIRE_PREFLIGHT    = true          [.nexus/env]
     HEADROOM_ALLOW_FULL_RETRIEVAL = false         [.nexus/env]
     HEADROOM_RETRIEVAL_MAX_LINES  = 200           [.nexus/env]
     HEADROOM_RETRIEVAL_MAX_CHARS  = 24000         [.nexus/env]
     ANTHROPIC_API_KEY             = sk-...        [.env.nexus.local]

   Dry run — would exec: opencode

Env resolution order

.nexus/env              (1) platform plugin vars — lowest priority
.env.nexus.local        (2) project secrets — overrides (1)
shell / process.env     (3) already-set vars — never overwritten

nexus run lifecycle

Since v0.11.0, nexus run wraps the environment injection described above with a full pre-launch and post-session lifecycle.

Pre-launch check suite

Before launching, nexus run verifies:

• Workspace state (linked project, clean .nexus/ cache)
• Auth (valid stored credentials)
• MCP configuration (opencode.json / .claude/mcp.json reference the current project)
• Plugin environment variables (.nexus/env present and current)
• Tool binary availability on $PATH
• Headroom preflight mode (live-verified transform vs. silently-downgraded observe, see Preflight and status checks)

Pass --skip-checks to bypass the entire suite (not recommended outside of trusted CI environments).

Launch countdown and confirmation

After checks pass, nexus run shows a short countdown before exec-launching the target tool, giving you a window to abort if something looks wrong. Use --force to skip the countdown and launch immediately, and --exec to replace the current process image (execve) instead of spawning a child process.

Post-session summary

When the launched tool exits, nexus run prints a summary covering:

• Git activity during the session (files changed, commits made)
• Token usage and estimated cost for the session
• Nexus activity stats (sessions, tasks, and Dispatches touched)
• Headroom compression stats, if the plugin was active

Plugin environment

Nexus plugins (like nexus-headroom-intercept) run inside the OpenCode main process and read configuration from process.env. The opencode.json MCP server environment block only reaches MCP subprocesses — not plugins. This is why plugin vars need a separate delivery path.

.nexus/env — platform-managed plugin vars

nexus pull and nexus init write .nexus/env from the project's plugin_env field in the af_export API response. This field is derived from the project agent's plugin configuration stored in the Nexus platform.

# .nexus/env — Platform-managed plugin environment variables
# Generated by: nexus pull
# DO NOT edit manually — overwritten by nexus pull / nexus init

HEADROOM_MODE=transform
HEADROOM_DEBUG=false
HEADROOM_REQUIRE_PREFLIGHT=true
HEADROOM_ALLOW_FULL_RETRIEVAL=false
HEADROOM_RETRIEVAL_MAX_LINES=200
HEADROOM_RETRIEVAL_MAX_CHARS=24000

The file is git-ignored (.nexus/.gitignore contains env). It contains only non-sensitive, platform-configured values — never secrets.

Delivery paths by environment

Updating plugin configuration

Plugin settings are managed in the Nexus dashboard under Project > Agent Setup > Plugins. After saving changes, run nexus pull to regenerate .nexus/env and then restart OpenCode (or use nexus run).

When to use nexus run vs devbox

Offline mode

When .nexus/env already exists on disk (written by a previous nexus pull), nexus run --no-db works without any network connection. The af_export API call is skipped and the cached env file is used as-is:

nexus run --no-db      # use .nexus/env from disk, skip platform API

This is safe for short offline periods. Run nexus pull the next time you have connectivity to refresh plugin configuration.

.nexus/env vs .env.nexus.local

Users familiar with dotenv conventions sometimes confuse these two files:

Rule of thumb: never put secrets in .nexus/env and never put plugin config in .env.nexus.local. The files serve different purposes and have different owners.

Troubleshooting

Plugin runs in observe mode instead of transform

The plugin defaults to observe when the preflight check fails or HEADROOM_MODE is not set. Diagnose with:

nexus run --dry-run    # check HEADROOM_MODE value and source

If HEADROOM_MODE shows observe in the dry-run output, run nexus pull to refresh .nexus/env from the platform. If the variable is missing entirely, check Project > Agent Setup > Plugins in the dashboard and confirm Headroom is enabled.

If HEADROOM_MODE shows transform in the dry-run but observe in practice, check the plugin log:

HEADROOM_DEBUG=true nexus run   # writes .nexus/headroom-intercept.jsonl

nexus run exits with "tool not found"

The tool binary (opencode by default) must be on $PATH. Install OpenCode globally or specify the full path:

nexus run --tool /usr/local/bin/opencode

Preflight and status checks

nexus preflight validates the local environment is ready for Nexus:

nexus status (server-verified since v0.16.0) confirms project existence and access against the Nexus API rather than trusting cached local state.

Claude Code projects

Since nexus-cli 0.28.5, the CLI supports the configurable Claude Code workspace and the curated plugins of NEXUS-APP 0.15.0 and 0.16.0.

Workspace layout and Zellij config (0.28.5, 0.28.7)

• nexus pull and nexus init write your personal layout (.nexus/claude/workspace.local.kdl) and Zellij settings (.nexus/claude/zellij.local.kdl) after checking path and sha256, and add them to .git/info/exclude.
• Both are recorded in the pull manifest: regenerated on every pull, a local edit is reported and kept unless --force (not -y); nexus status, diff and reset show them, nexus push refuses them.
• nexus run starts Zellij with --config <zellij.local.kdl> --layout <workspace.local.kdl>. Before the first pull it falls back to the committed .nexus/claude/nexus-claude.kdl and the global Zellij config, with a WARN row. An explicit ZELLIJ_CONFIG_FILE wins.

Agent observer (0.28.5, 0.28.6)

nexus status --agents            # snapshot
nexus status --agents --watch    # live, redraws once per second
nexus status --agents --json     # full DTO, full model ids
nexus status --agents --all      # include sessions finished > 30 min ago

Reads .nexus/claude/observer/events.jsonl locally (no login, no network). Model names are shown compact (haiku-4-5).

nexus doctor claude (0.28.5 to 0.28.7)

Detects claude, zellij, lazygit, ccusage and delta. The required set comes from the workspace's requires; missing required tools fail (exit 1), optional ones are INFO, and the Claude Code version is checked against the supported range. --fix prints devbox, brew or npm install commands and runs them only after confirmation or -y. When the observer is set to AgentHUD, doctor checks agenthud as an unsupported third-party tool and only prints its install instruction. Also shows which Zellij config the workspace uses. Supports --output json.

Plugin installation (0.28.8)

nexus pull --force and nexus run install missing managed Claude Code plugins at project scope (claude plugin install ... --scope project), adding the marketplace first when needed. Results are reported as INSTALLED, PRESENT, FAILED or RELEASED; a failure never blocks. NEXUS_SKIP_PLUGIN_SYNC=1 skips the step. nexus status marks managed plugins [managed]. Details: Claude Code Plugins.

MCP binding and export warnings (0.28.6)

• nexus init, nexus pull and nexus run write NEXUS_PROJECT_ID into mcpServers.nexus.env of .mcp.json, so project-scoped MCP tools work without an explicit project_id. Existing workspaces are repaired on the next nexus run.
• export_warnings (for example actors_not_exported) are now printed for Claude Code projects too, without a prompt.

nexus status layout (0.28.10)

All sections (General, Claude Code runtime, Git Identity Verification) share one key column. Git identity rows put the status before the expected value (local=<value> [OK] expected=<value>), so the status stays visible next to long values such as signing keys; nexus git verify uses the same layout.

Directives, skills and shadow

Directives (0.28.9, 0.28.10)

• .nexus/directives.md is a compact rule list: one - MUST: <rule> or - SHOULD: <rule> line per directive, grouped by category in server order.
• Claude Code projects get the rules in .claude/rules/15-nexus-directives.md; the root CLAUDE.md bootstrap names that file (readable copy: directives.md). The root CLAUDE.md is still created once and never overwritten.
• See Directives.

Skills (0.28.8, 0.28.9)

• Skill resource files are written next to SKILL.md in .claude/skills/<skill>/ and the agentic root.
• invocation: user renders disable-model-invocation: true into the SKILL.md frontmatter. See Skills.

Shadow and git exclude (0.28.9, 0.28.10)

• af_export.git_exclude is applied on every pull as a managed block in .git/info/exclude (# >>> nexus managed exclude (server)). Your own lines are never touched; tracked files are never untracked automatically (pull prints a git rm -r --cached <path> hint).
• nexus shadow on|ai|nexus|off sets the project's policy.shadow (on = ai) and applies the exclude list at once; nexus shadow status shows the server level and block.
• See Project Settings.

Upgrading

For NEXUS-APP 0.16.x, use nexus-cli 0.28.10 or later:

nexus upgrade
nexus pull --force

Then restart running agent sessions: a running session keeps the files and environment it started with.

Config precedence

Since v0.16.0, nexus config uses a git-style two-layer configuration model:

• --local — project-scoped, stored under .nexus/config.toml in the current workspace
• --global — machine-wide, stored under ~/.config/nexus/config.toml

nexus config set run.default_tool=cursor --local   # this project only
nexus config set run.default_tool=opencode --global # machine default

Read-side precedence

--local value    (1) highest priority, if a local config file exists
--global value    (2) falls back to the global config
built-in default (3) lowest priority

nexus config show displays the resolved value for each key along with its provenance (which layer it was read from), so it is always clear whether a setting came from the project or the machine.

Credential resolution

Nexus API credentials and project bindings are resolved in the following order, highest priority first:

1. CLI flag            (e.g. --project-id)
2. Environment variable (NEXUS_API_URL, NEXUS_PRIVATE_TOKEN, NEXUS_PROJECT_TOKEN)
3. Local config          (--local layer)
4. Global config         (--global layer)
5. Built-in default

Since v0.14.1 and v0.16.6, nexus run also auto-syncs the MCP credentials baked into opencode.json and .claude/mcp.json with the currently logged-in Nexus account on every invocation, so a stale token in a generated config file no longer silently diverges from the active login.

Workspace sync: push and stash

nexus push (v0.14.0) and nexus stash (v0.15.1) round out bidirectional workspace sync, complementing nexus pull.

nexus push

nexus push publishes local workspace state (directives, skill assignments, and other project-scoped artifacts) back to the platform using a fork-based publish model: your local changes are proposed as a fork of the project's current state rather than overwriting it directly.

nexus push                  # publish local changes as a fork
nexus push --adopt-local    # first-time bootstrap: adopt local state as the project baseline

nexus push requires a prior nexus pull for the current project (an origin guard prevents pushing from a workspace that was never synced from the platform).

nexus stash

nexus stash save   # snapshot local workspace state before a pull or push
nexus stash pop     # restore the most recent snapshot
nexus stash list    # list saved snapshots

Use nexus stash save before running nexus pull if you have uncommitted local changes you are not ready to publish with nexus push, then nexus stash pop afterward to reapply them.

Project tokens

nexus project link|rotate|unlink|status (v0.15.0) manages the project-scoped inference token (nxs_proj_*) used by the Nexus Model Gateway.

Project tokens are stored alongside other workspace credentials and resolved using the same precedence order as other Nexus credentials.

Import workflow

nexus import scans the current workspace for pre-existing agentic configuration files and imports them into the linked Nexus project. This is the recommended way to onboard existing projects alongside the platform-managed workflow.

Detected files: CLAUDE.md, AGENTS.md, .cursorrules, copilot-instructions.md, .windsurf/rules/*.md, GEMINI.md

What happens:

• Detected agentic files are ingested as unclassified items for review and promotion
• Directive-like sections (rules, guidelines, conventions) are extracted and created as disabled project directives
• Markdown links to local documents (e.g. docs/*.md) are resolved and ingested as referenced documents
• Exported agent files (.nexus/CLAUDE.md, .nexus/AGENTS.md) automatically include a cross-reference block pointing to the original customer files

During nexus init, the CLI automatically detects existing agentic files and offers to run the import.

nexus pull / nexus init behavior changes

• export_warnings gate (v0.16.1): if the platform export reports model-routing or provider configuration issues, nexus pull and nexus init now stop and show the warnings with an interactive confirm prompt before writing files, rather than exporting silently. Pass --yes or --force to bypass the prompt in non-interactive contexts.
• opencode_instructions merge (v0.16.2): project-level opencode_instructions are now merged into the generated opencode.json instead of requiring manual copy-paste.
• NEXUS_PROJECT_ID in the MCP environment block: nexus pull now writes NEXUS_PROJECT_ID into the MCP server environment block of opencode.json, so MCP subprocesses can resolve the active project without an extra lookup.

Workspace cache

The CLI creates a .nexus/ directory in your project root to store workspace metadata, project bindings, and cached configuration. This directory is automatically excluded from Git via .git/info/exclude (not .gitignore) to avoid polluting the shared ignore file. The nexus deinit command cleans up both the cache directory and the exclude entries.

Security hardening

A set of CLI-specific security fixes shipped alongside the v0.13.5 platform hardening pass and later releases:

• Path traversal protection on sync manifest paths used by nexus pull and nexus push
• Automatic git-exclude of token-bearing config files, so a token file can never be accidentally committed even without a .gitignore entry
• Install-script checksum verification for nexus upgrade, matching the SHA-256 verification already performed by the install one-liner
• Allowlist sanitization of server-supplied prerequisite check commands run during nexus preflight
• Reduced PAT token exposure in preflight and status output (tokens are masked rather than printed in full)
• nexus shadow git index safety fix (v0.13.1): a guard now prevents nexus shadow from silently staging the deletion of files that have existing commit history
• Gitleaks config fixed (v0.28.10): the repository's gitleaks pre-commit config now extends the built-in ruleset (before, the custom config replaced it and every scan passed); a CI self-test guards it. A full history scan found no real secrets.
• Clean error output (v0.16.3): raw Rust stack backtraces no longer leak into CLI output on auth or API errors, regardless of the RUST_BACKTRACE environment variable

Cost control tools

nexus pull automatically configures two token-saving tools when enabled for a project:

RTK — Runtime Token Killer

Filters and compresses CLI output before it reaches the agent context (60-90% savings on build/test/lint output).

# Install the RTK binary
# See: https://www.rtk-ai.app/#install

# Install the OpenCode plugin (once per machine)
rtk init -g --opencode

# After nexus pull, trust project filters
rtk trust

The .rtk/filters.toml file is auto-generated from the project's codebase character presets (configured in the Nexus dashboard under Project > Plugins) and synced on every nexus pull.

Headroom — Context Compression Plugin

Policy-based context compression via the nexus-headroom-intercept OpenCode plugin and the Headroom MCP server. Reduces token consumption by 60–95% on large tool responses.

pip install "headroom-ai[mcp]"
headroom --version     # verify install

After nexus pull:

• opencode.json is updated with the nexus-headroom MCP server block
• .nexus/env is written with the project's HEADROOM_* configuration

Use nexus run to launch OpenCode with the plugin vars in scope, or let devbox shell source them automatically via dbx_init.sh.

See Plugins — nexus-headroom-intercept for the full plugin reference including env vars, compression profiles, and retrieval semantics.