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

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 checks

nexus preflight validates the local environment is ready for Nexus:

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.

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.

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.