@agent-nexus/cli

Official CLI for the Nexus AI agent platform. Manage agents, workflows, deployments, knowledge bases, and more from your terminal.

• Wraps the full Nexus Public API v1
• 24 command groups, 120+ subcommands
• Table, record, and JSON output modes
• Pipe-friendly: stdin input, --json output, composable with jq
• Zero config after nexus auth login
• Node.js 18+

Status: BETA -- The CLI surface is stable but may evolve before 1.0.

Table of Contents

• Installation
• Authentication
• Quick Start
• Global Options
• Input Patterns
• Output Modes
• Commands
• Common Patterns
• SDK Cross-Reference
• Error Handling
• Troubleshooting
• Configuration Files
• Related Resources
• License

Installation

# Install globally
npm install -g @agent-nexus/cli

# Or with pnpm
pnpm add -g @agent-nexus/cli

# Or with yarn
yarn global add @agent-nexus/cli

Run a one-off command without installing:

npx @agent-nexus/cli agent list

Verify the installation:

nexus --version

Upgrade to the latest version:

nexus upgrade

The CLI checks for updates once per day and prints a notice to stderr when a newer version is available. This check never delays command execution.

Authentication

Interactive Login

nexus auth login

This opens the Nexus settings page in your browser. Copy your API key and paste it at the prompt. The key is validated against the API before being saved.

Non-Interactive Login

For CI/CD or scripting:

# Via flag
nexus auth login --api-key nxs_abc123

# Via environment variable (no login needed)
export NEXUS_API_KEY=nxs_abc123

Verify Authentication

nexus auth whoami

Prints the API base URL and a masked version of your key (e.g., nxs_abc1...3def).

Logout

nexus auth logout

Removes stored credentials from ~/.nexus-mcp/config.json.

API Key Resolution

The CLI resolves the API key in this order (first match wins):

| Priority | Source | Example | | -------- | ----------------------- | ------------------------------------ | | 1 | --api-key flag | nexus agent list --api-key nxs_... | | 2 | NEXUS_API_KEY env var | export NEXUS_API_KEY=nxs_... | | 3 | Config file | Written by nexus auth login |

Base URL Resolution

| Priority | Source | Default | | -------- | ------------------------ | ------------------------------------------------------------------------- | | 1 | --base-url flag | | | 2 | NEXUS_BASE_URL env var | | | 3 | Config file | | | 4 | NEXUS_ENV env var | production = https://api.nexusgpt.io, dev = http://localhost:3001 | | 5 | Default | https://api.nexusgpt.io |

Multi-Profile Support

The CLI supports multiple named profiles for managing different organizations or environments.

Create profiles

# Interactive (opens browser, prompts for key and profile name)
nexus auth login

# Non-interactive with explicit profile name
nexus auth login --profile work --api-key nxs_abc123
nexus auth login --profile personal --api-key nxs_xyz789

Switch between profiles

nexus auth switch work
nexus auth switch personal

List all profiles

nexus auth list
#  PROFILE    ORGANIZATION   BASE URL
# ▸ work      Acme Corp      https://api.nexusgpt.io
#   personal  My Startup     https://api.nexusgpt.io

Pin a directory to a profile

Create a .nexusrc file in your project directory so the CLI automatically uses the right profile:

cd ~/projects/acme
nexus auth pin work
# Creates .nexusrc with { "profile": "work" }

cd ~/projects/startup
nexus auth pin personal

Check which profile is active

nexus auth status
# Using profile "work" (Acme Corp) — .nexusrc at /Users/you/projects/acme/.nexusrc

Profile Resolution Order

When determining which profile to use, the CLI checks (first match wins):

| Priority | Source | Example | | -------- | --------------------------------------- | ------------------------------------------ | | 1 | --api-key flag or NEXUS_API_KEY env | Bypasses profiles entirely | | 2 | --profile flag | nexus agent list --profile work | | 3 | NEXUS_PROFILE env var | export NEXUS_PROFILE=work | | 4 | .nexusrc file | Walks up directory tree to find .nexusrc | | 5 | Active profile | Set by nexus auth switch | | 6 | "default" profile | Fallback |

Remove profiles

nexus auth logout           # removes active profile
nexus auth logout work      # removes specific profile
nexus auth logout --all     # removes everything

nexus auth unpin            # removes .nexusrc from current directory

Quick Start

A complete walkthrough: create an agent, give it a knowledge base, deploy it, and test it.

# 1. Authenticate
nexus auth login

# 2. Create an agent
nexus agent create \
  --first-name "Support" \
  --last-name "Bot" \
  --role "Customer Support" \
  --prompt "You are a helpful customer support agent. Answer questions using the knowledge base."

# 3. Upload a document to the knowledge base
nexus document upload ./product-faq.pdf

# 4. Create a collection (retrieval-augmented generation index)
nexus collection create --name "Product FAQ"

# 5. Attach the document to the collection
nexus collection attach-documents <collection-id> --document-ids <document-id>

# 6. Attach the collection as a tool on the agent
nexus agent-tool create <agent-id> \
  --type COLLECTION \
  --collection-id <collection-id> \
  --label "FAQ Search"

# 7. Deploy the agent as a web widget
nexus deployment create \
  --name "Support Widget" \
  --type web \
  --agent-id <agent-id>

# 8. Test via the emulator
nexus emulator session create <deployment-id>
nexus emulator send <deployment-id> <session-id> \
  --text "How do I reset my password?"

Tip: Add --json to any command and pipe to jq to extract IDs:

AGENT_ID=$(nexus agent create --first-name Bot --last-name Helper --role QA --json | jq -r '.id')

Global Options

These flags are available on every command:

| Flag | Description | | ------------------ | ------------------------------------------------- | | --json | Output results as JSON (for scripting and piping) | | --api-key <key> | Override the API key for this invocation | | --base-url <url> | Override the API base URL | | --profile <name> | Use a specific named profile | | --no-auto-update | Disable automatic CLI updates for this invocation | | -v, --version | Print the CLI version and exit | | --help | Show help for any command or subcommand |

Environment Variables

| Variable | Description | | ---------------- | --------------------------------------------------------------- | | NEXUS_API_KEY | API key (used when --api-key flag and config file are absent) | | NEXUS_BASE_URL | API base URL override | | NEXUS_ENV | Environment name: production (default) or dev | | NEXUS_PROFILE | Profile name override (same as --profile flag) | | NO_COLOR | Disable all color output (no-color.org) |

Input Patterns

The CLI offers flexible input for create and update commands.

The --body Flag

Most create/update commands accept --body for raw JSON input:

# Inline JSON
nexus agent create --body '{"firstName":"Ada","lastName":"Bot","role":"Assistant"}'

# From a JSON file
nexus agent create --body payload.json

# From stdin
cat payload.json | nexus agent create --body -
echo '{"firstName":"Ada","lastName":"Bot","role":"Assistant"}' | nexus agent create --body -

Flag-Over-Body Merge

When you use both --body and individual flags, flags take precedence. The body provides defaults; flags override specific fields:

# Body sets firstName and role; --role flag overrides the role field
nexus agent create \
  --body '{"firstName":"Ada","lastName":"Bot","role":"Assistant"}' \
  --role "Senior Assistant"
# Result: { firstName: "Ada", lastName: "Bot", role: "Senior Assistant" }

File and Stdin Input

Flags like --prompt, --content, and --description accept:

| Input | Example | | ------------ | ---------------------------------------------------------------- | | Literal text | --prompt "You are a helpful agent" | | File path | --prompt ./system-prompt.md (auto-detected if the file exists) | | Stdin | --prompt - (reads from stdin) |

# Load a prompt from a markdown file
nexus agent create --first-name Bot --last-name Helper --role QA --prompt ./prompt.md

# Pipe a prompt from another command
generate-prompt | nexus agent update abc-123 --prompt -

Pagination

List commands support pagination:

nexus agent list --page 2 --limit 50

The pagination footer shows total, page, and whether more available.

Output Modes

Table (Default for Lists)

ID                                    FIRST NAME       STATUS
────────────────────────────────────  ───────────────  ──────
abc-123-def-456                       Support Bot      ACTIVE
ghi-789-jkl-012                       Sales Agent      DRAFT

3 total · page 1 · more available

Record (Default for Single Resources)

ID        abc-123-def-456
Name      Support Bot
Role      Customer Support
Status    ACTIVE
Created   2026-03-15T10:30:00.000Z

JSON (--json)

nexus agent list --json

{
  "data": [{ "id": "abc-123", "firstName": "Support", "lastName": "Bot", "status": "ACTIVE" }],
  "meta": { "total": 3, "page": 1, "hasMore": true }
}

nexus agent get abc-123 --json

{
  "id": "abc-123",
  "firstName": "Support",
  "lastName": "Bot",
  "role": "Customer Support",
  "status": "ACTIVE"
}

Important: Always use --json when piping output to jq or other tools. The default table output is for humans and will break parsers.

Error Output in JSON Mode

When --json is active, errors are also returned as JSON:

{
  "error": {
    "message": "Authentication failed — invalid or missing API key.",
    "hint": "Run \"nexus auth login\" to re-authenticate, or set NEXUS_API_KEY."
  }
}

Commands

All commands follow the pattern: nexus <group> <action> [arguments] [options]

Core Platform

| Command | Subcommands | Description | | ---------------------------------------------------------- | ---------------------------------------------------------------- | ------------------------- | | auth | login logout switch list pin unpin status whoami | Authentication | | agent | list get create update delete duplicate | AI agent management | | agent-tool | list get create update delete | Agent tool configurations | | version | list get create update delete restore publish | Prompt version management | | folder | list create update delete assign | Agent folder organization | | model | list | Available AI models |

Workflows & Execution

| Command | Subcommands | Description | | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | --------------------------- | | workflow | list get create update delete duplicate publish unpublish validate test | Workflow CRUD and lifecycle | | workflow node | create get update delete test variables output-format reload-props | Workflow node operations | | workflow edge | create delete | Node connections | | workflow branch | list create update delete | Branching logic | | execution | list get graph output retry export node-result | Workflow execution history |

Knowledge & Documents

| Command | Subcommands | Description | | ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | --------------------- | | document | list get upload create-text add-website import-google-sheets delete | Knowledge documents | | collection | list get create update delete search documents attach-documents remove-document stats | Knowledge collections |

Skills & Tasks

| Command | Subcommands | Description | | ---------------------------------------------------------------- | ------------------------------------------------- | ---------------------- | | task | list get create update delete execute | AI task management | | template | list get create upload generate | Document templates | | external-tool | list get create update delete test | OpenAPI external tools |

Deployment & Testing

| Command | Subcommands | Description | | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------ | --------------------------------- | | deployment | list get create update delete duplicate stats embed-config embed-config-update | Agent deployments | | deployment folder | list create update delete assign | Deployment folder organization | | emulator | send | Send messages to test deployments | | emulator session | create list get delete | Emulator session management | | emulator scenario | save list get replay delete | Save and replay test scenarios |

Marketplace & Discovery

| Command | Subcommands | Description | | ---------------------------------------------- | ------------------------------------------------------------------------ | -------------------------- | | tool | search get credentials connect resolve-options skills test | Marketplace tool discovery |

Analytics & Operations

| Command | Subcommands | Description | | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | -------------------------- | | analytics | overview feedback export | Organization analytics | | eval | (subgroups: session, dataset, execute, judge, results, formats, judges) | AI task evaluation | | ticket | list get create update comment comments | Bug and feature tracking | | phone-number | search buy list get release | Phone number management | | channel | setup connection list\|create whatsapp-sender list\|create\|get | Channel setup orchestrator | | prompt-assistant | chat get-thread delete-thread | AI-assisted prompt writing |

Utility

| Command | Subcommands | Description | | ---------------------------------------------------- | --------------- | ------------------------------ | | api | (passthrough) | Call any API endpoint directly | | docs | (topic browser) | View built-in documentation | | upgrade | (self-update) | Upgrade the CLI to latest |

Full reference: See docs/command-reference.md for complete documentation of every command, option, and example.

Common Patterns

Extract IDs with jq

# Get the ID of a newly created agent
AGENT_ID=$(nexus agent create \
  --first-name Bot --last-name Helper --role QA --json | jq -r '.id')
echo "Created agent: $AGENT_ID"

Pipe JSON Output

# List all active agent IDs
nexus agent list --json | jq -r '.data[] | select(.status == "ACTIVE") | .id'

# Count deployments by type
nexus deployment list --json | jq '.data | group_by(.type) | map({type: .[0].type, count: length})'

Bulk Operations

# Update all agents to use a specific model
nexus agent list --json | jq -r '.data[].id' | while read id; do
  nexus agent update "$id" --model gpt-4o
  echo "Updated $id"
done

Raw API Passthrough

For endpoints without a dedicated CLI command:

# GET request
nexus api GET /models

# POST with inline body
nexus api POST /agents --body '{"firstName":"Test","lastName":"Bot","role":"QA"}'

# GET with query parameters
nexus api GET /agents --query page=1 --query limit=5

# POST with body from file
nexus api PATCH /agents/abc-123 --body payload.json

# POST with body from stdin
echo '{"text":"hello"}' | nexus api POST /emulator/dep-1/sessions/s-1/messages --body -

Suppress Confirmation Prompts (CI/CD)

# Skip delete confirmation
nexus agent delete abc-123 --yes

# Preview what would be deleted without executing
nexus agent delete abc-123 --dry-run

Load Prompts from Files

# Create an agent with a prompt from a markdown file
nexus agent create \
  --first-name Support --last-name Bot --role "Customer Support" \
  --prompt ./prompts/support-agent.md

# Update an agent's prompt from stdin
cat new-prompt.md | nexus agent update abc-123 --prompt -

Workflow Build Pipeline

# Create, build, validate, test, and publish in one pipeline
WF_ID=$(nexus workflow create --name "Lead Qualifier" --json | jq -r '.id')

nexus workflow node create $WF_ID --type agentInputTrigger --name "Start"
nexus workflow node create $WF_ID --type aiTask --name "Qualify" \
  --body '{"data":{"taskId":"task-123"}}'

nexus workflow validate $WF_ID
nexus workflow test $WF_ID --input '{"message":"I want to buy 100 units"}'
nexus workflow publish $WF_ID

SDK Cross-Reference

Every CLI command maps to an SDK method. Use the SDK (@agent-nexus/sdk) when building applications; use the CLI for scripting and exploration.

| CLI Command | SDK Equivalent | | --------------------------------------- | ----------------------------------------------------- | | nexus agent list | client.agents.list() | | nexus agent get <id> | client.agents.get(id) | | nexus agent create --first-name X ... | client.agents.create({ firstName: "X", ... }) | | nexus agent update <id> --role Y | client.agents.update(id, { role: "Y" }) | | nexus agent delete <id> | client.agents.delete(id) | | nexus agent-tool list <agentId> | client.agents.tools.list(agentId) | | nexus version list <agentId> | client.agents.versions.list(agentId) | | nexus workflow list | client.workflows.list() | | nexus workflow publish <id> | client.workflows.publish(id) | | nexus document upload <file> | client.documents.uploadFile(file) | | nexus collection create --name X | client.documents.createCollection({ name: "X" }) | | nexus deployment create --name X ... | client.deployments.create({ name: "X", ... }) | | nexus emulator session create <depId> | client.emulator.createSession(depId) | | nexus emulator send <depId> <sessId> | client.emulator.sendMessage(depId, sessId, { ... }) | | nexus tool search --query X | client.tools.search({ query: "X" }) | | nexus analytics overview | client.analytics.getOverview() | | nexus model list | client.models.list() | | nexus ticket create --title X ... | client.tickets.create({ title: "X", ... }) | | nexus phone-number list | client.phoneNumbers.list() | | nexus channel setup --type WHATSAPP | client.channels.getSetupStatus("WHATSAPP") | | nexus channel connection create | client.channels.createConnection() | | nexus channel whatsapp-sender create | client.channels.createWhatsAppSender({ ... }) |

Full SDK documentation: See @agent-nexus/sdk README

Error Handling

The CLI catches all errors and prints actionable messages with hints.

Error Types

| Error | Cause | Hint | | -------------------------- | ------------------------------------ | ------------------------------------------------------ | | Authentication failed | Invalid, missing, or expired API key | Run nexus auth login or set NEXUS_API_KEY | | Not found (404) | Resource ID doesn't exist | Run nexus <resource> list to find valid IDs | | Validation error (422) | Invalid request body or parameters | Add --json to see the details field | | Connection error | Network issue or wrong base URL | Check --base-url and network connectivity | | API error (5xx) | Server-side error | Retry after a moment; report via nexus ticket create |

Exit Codes

| Code | Meaning | | ---- | ------------------------------------------------------------- | | 0 | Success | | 1 | Any error (authentication, API, validation, connection, etc.) |

Error Format

Human-readable (default):

Error: Authentication failed — invalid or missing API key.
  Run "nexus auth login" to re-authenticate, or set NEXUS_API_KEY.

JSON (--json):

{
  "error": {
    "message": "Authentication failed — invalid or missing API key.",
    "hint": "Run \"nexus auth login\" to re-authenticate, or set NEXUS_API_KEY."
  }
}

Troubleshooting

"No API key found"

Error: No API key found. Set NEXUS_API_KEY or run:
  nexus auth login

Fix: Run nexus auth login or set the NEXUS_API_KEY environment variable.

"Invalid key format -- keys start with nxs_"

Fix: Copy the full API key from Settings > API Keys, including the nxs_ prefix.

"Could not reach the Nexus API"

Fix: Check your network connection. If using a custom base URL, verify it:

nexus auth whoami  # shows the current base URL

"Validation failed (HTTP 401)"

Fix: Your API key may be expired or revoked. Regenerate it at Settings > API Keys and run nexus auth login again.

Colors Not Showing

The CLI disables colors when:

• NO_COLOR environment variable is set
• --no-color flag is passed
• stdout is not a TTY (e.g., piped to a file or another command)

Update Check Not Working

The version check cache is stored at ~/.nexus-mcp/version-check.json. Delete it to force a fresh check:

rm ~/.nexus-mcp/version-check.json
nexus agent list  # triggers a new check

Upgrade Failed

If nexus upgrade fails (e.g., permission denied), run the install manually:

sudo npm install -g @agent-nexus/cli@latest

Configuration Files

| File | Purpose | Permissions | | --------------------------------- | ------------------------------------------------------------- | ----------- | | ~/.nexus-mcp/config.json | Profiles with API keys and base URLs | 0600 | | ~/.nexus-mcp/version-check.json | Update check cache (auto-managed, checked once/day) | 0600 | | .nexusrc | Directory-level profile pinning (created by nexus auth pin) | — |

The ~/.nexus-mcp/ directory is created with 0700 permissions. This path is shared with the @nexus/mcp-server package.

Config File Format (V2)

{
  "activeProfile": "work",
  "profiles": {
    "work": {
      "apiKey": "nxs_...",
      "baseUrl": "https://api.nexusgpt.io",
      "orgName": "Acme Corp",
      "orgId": "org_..."
    },
    "personal": {
      "apiKey": "nxs_...",
      "orgName": "My Startup"
    }
  }
}

.nexusrc Format

{ "profile": "work" }

Place in your project root. The CLI walks up the directory tree to find it. Consider adding .nexusrc to .gitignore.

Related Resources

| Resource | Link | | --------------------- | ------------------------------------------------------------------------------ | | SDK | @agent-nexus/sdk | | Product Documentation | packages/docs | | Claude Code Skills | packages/claude-code-skills | | API Reference | https://api.nexusgpt.io/api/public/v1 | | Dashboard | app.nexusgpt.io | | CLI Command Reference | docs/command-reference.md | | Input/Output Guide | docs/input-output-patterns.md | | Common Gotchas | docs/gotchas.md | | Recipes | docs/recipes.md | | Report Issues | nexus ticket create --type BUG --title "..." --description "..." | | Request Features | nexus ticket create --type FEATURE_REQUEST --title "..." --description "..." |

License

MIT