@agent-nexus/cli 0.1.5 → 0.1.7

package/README.md

@@ -0,0 +1,765 @@
+# @agent-nexus/cli
+
+Official CLI for the [Nexus](https://nexusgpt.io) AI agent platform. Manage agents, workflows, deployments, knowledge bases, and more from your terminal.
+
+- Wraps the full [Nexus Public API v1](../sdk)
+- 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](#installation)
+- [Authentication](#authentication)
+- [Quick Start](#quick-start)
+- [Global Options](#global-options)
+- [Input Patterns](#input-patterns)
+- [Output Modes](#output-modes)
+- [Commands](#commands)
+- [Common Patterns](#common-patterns)
+- [SDK Cross-Reference](#sdk-cross-reference)
+- [Error Handling](#error-handling)
+- [Troubleshooting](#troubleshooting)
+- [Configuration Files](#configuration-files)
+- [Related Resources](#related-resources)
+- [License](#license)
+
+---
+
+## Installation
+
+```bash
+# 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:
+
+```bash
+npx @agent-nexus/cli agent list
+```
+
+Verify the installation:
+
+```bash
+nexus --version
+```
+
+Upgrade to the latest version:
+
+```bash
+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
+
+```bash
+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:
+
+```bash
+# Via flag
+nexus auth login --api-key nxs_abc123
+
+# Via environment variable (no login needed)
+export NEXUS_API_KEY=nxs_abc123
+```
+
+### Verify Authentication
+
+```bash
+nexus auth whoami
+```
+
+Prints the API base URL and a masked version of your key (e.g., `nxs_abc1...3def`).
+
+### Logout
+
+```bash
+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
+
+```bash
+# 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
+
+```bash
+nexus auth switch work
+nexus auth switch personal
+```
+
+#### List all profiles
+
+```bash
+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:
+
+```bash
+cd ~/projects/acme
+nexus auth pin work
+# Creates .nexusrc with { "profile": "work" }
+
+cd ~/projects/startup
+nexus auth pin personal
+```
+
+#### Check which profile is active
+
+```bash
+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
+
+```bash
+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.
+
+```bash
+# 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:
+>
+> ```bash
+> 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](https://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:
+
+```bash
+# 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:
+
+```bash
+# 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)                                  |
+
+```bash
+# 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:
+
+```bash
+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`)
+
+```bash
+nexus agent list --json
+```
+
+```json
+{
+  "data": [{ "id": "abc-123", "firstName": "Support", "lastName": "Bot", "status": "ACTIVE" }],
+  "meta": { "total": 3, "page": 1, "hasMore": true }
+}
+```
+
+```bash
+nexus agent get abc-123 --json
+```
+
+```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:
+
+```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`](docs/command-reference.md#nexus-auth)             | `login` `logout` `switch` `list` `pin` `unpin` `status` `whoami` | Authentication            |
+| [`agent`](docs/command-reference.md#nexus-agent)           | `list` `get` `create` `update` `delete` `duplicate`         | AI agent management       |
+| [`agent-tool`](docs/command-reference.md#nexus-agent-tool) | `list` `get` `create` `update` `delete`                     | Agent tool configurations |
+| [`version`](docs/command-reference.md#nexus-version)       | `list` `get` `create` `update` `delete` `restore` `publish` | Prompt version management |
+| [`folder`](docs/command-reference.md#nexus-folder)         | `list` `create` `update` `delete` `assign`                  | Agent folder organization |
+| [`model`](docs/command-reference.md#nexus-model)           | `list`                                                      | Available AI models       |
+
+### Workflows & Execution
+
+| Command                                                              | Subcommands                                                                                 | Description                 |
+| -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | --------------------------- |
+| [`workflow`](docs/command-reference.md#nexus-workflow)               | `list` `get` `create` `update` `delete` `duplicate` `publish` `unpublish` `validate` `test` | Workflow CRUD and lifecycle |
+| [`workflow node`](docs/command-reference.md#nexus-workflow-node)     | `create` `get` `update` `delete` `test` `variables` `output-format` `reload-props`          | Workflow node operations    |
+| [`workflow edge`](docs/command-reference.md#nexus-workflow-edge)     | `create` `delete`                                                                           | Node connections            |
+| [`workflow branch`](docs/command-reference.md#nexus-workflow-branch) | `list` `create` `update` `delete`                                                           | Branching logic             |
+| [`execution`](docs/command-reference.md#nexus-execution)             | `list` `get` `graph` `output` `retry` `export` `node-result`                                | Workflow execution history  |
+
+### Knowledge & Documents
+
+| Command                                                    | Subcommands                                                                                               | Description           |
+| ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | --------------------- |
+| [`document`](docs/command-reference.md#nexus-document)     | `list` `get` `upload` `create-text` `add-website` `import-google-sheets` `delete`                         | Knowledge documents   |
+| [`collection`](docs/command-reference.md#nexus-collection) | `list` `get` `create` `update` `delete` `search` `documents` `attach-documents` `remove-document` `stats` | Knowledge collections |
+
+### Skills & Tasks
+
+| Command                                                          | Subcommands                                       | Description            |
+| ---------------------------------------------------------------- | ------------------------------------------------- | ---------------------- |
+| [`task`](docs/command-reference.md#nexus-task)                   | `list` `get` `create` `update` `delete` `execute` | AI task management     |
+| [`template`](docs/command-reference.md#nexus-template)           | `list` `get` `create` `upload` `generate`         | Document templates     |
+| [`external-tool`](docs/command-reference.md#nexus-external-tool) | `list` `get` `create` `update` `delete` `test`    | OpenAPI external tools |
+
+### Deployment & Testing
+
+| Command                                                                  | Subcommands                                                                                      | Description                       |
+| ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------ | --------------------------------- |
+| [`deployment`](docs/command-reference.md#nexus-deployment)               | `list` `get` `create` `update` `delete` `duplicate` `stats` `embed-config` `embed-config-update` | Agent deployments                 |
+| [`deployment folder`](docs/command-reference.md#nexus-deployment-folder) | `list` `create` `update` `delete` `assign`                                                       | Deployment folder organization    |
+| [`emulator`](docs/command-reference.md#nexus-emulator)                   | `send`                                                                                           | Send messages to test deployments |
+| [`emulator session`](docs/command-reference.md#nexus-emulator-session)   | `create` `list` `get` `delete`                                                                   | Emulator session management       |
+| [`emulator scenario`](docs/command-reference.md#nexus-emulator-scenario) | `save` `list` `get` `replay` `delete`                                                            | Save and replay test scenarios    |
+
+### Marketplace & Discovery
+
+| Command                                        | Subcommands                                                              | Description                |
+| ---------------------------------------------- | ------------------------------------------------------------------------ | -------------------------- |
+| [`tool`](docs/command-reference.md#nexus-tool) | `search` `get` `credentials` `connect` `resolve-options` `skills` `test` | Marketplace tool discovery |
+
+### Analytics & Operations
+
+| Command                                                                | Subcommands                                                                           | Description                |
+| ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | -------------------------- |
+| [`analytics`](docs/command-reference.md#nexus-analytics)               | `overview` `feedback` `export`                                                        | Organization analytics     |
+| [`eval`](docs/command-reference.md#nexus-eval)                         | (subgroups: `session`, `dataset`, `execute`, `judge`, `results`, `formats`, `judges`) | AI task evaluation         |
+| [`ticket`](docs/command-reference.md#nexus-ticket)                     | `list` `get` `create` `update` `comment` `comments`                                   | Bug and feature tracking   |
+| [`phone-number`](docs/command-reference.md#nexus-phone-number)         | `search` `buy` `list` `get` `release`                                                 | Phone number management    |
+| [`prompt-assistant`](docs/command-reference.md#nexus-prompt-assistant) | `chat` `get-thread` `delete-thread`                                                   | AI-assisted prompt writing |
+
+### Utility
+
+| Command                                              | Subcommands   | Description                    |
+| ---------------------------------------------------- | ------------- | ------------------------------ |
+| [`api`](docs/command-reference.md#nexus-api)         | (passthrough)  | Call any API endpoint directly |
+| [`docs`](docs/command-reference.md#nexus-docs)       | (topic browser) | View built-in documentation    |
+| [`upgrade`](docs/command-reference.md#nexus-upgrade) | (self-update)  | Upgrade the CLI to latest      |
+
+> **Full reference:** See [docs/command-reference.md](docs/command-reference.md) for complete documentation of every command, option, and example.
+
+---
+
+## Common Patterns
+
+### Extract IDs with `jq`
+
+```bash
+# 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
+
+```bash
+# 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
+
+```bash
+# 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:
+
+```bash
+# 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)
+
+```bash
+# 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
+
+```bash
+# 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
+
+```bash
+# 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()`                          |
+
+> **Full SDK documentation:** See [@agent-nexus/sdk README](../sdk/README.md)
+
+---
+
+## 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`):**
+
+```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:
+
+```bash
+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](https://app.nexusgpt.io/app/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:
+
+```bash
+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:
+
+```bash
+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`](../mcp-server/) package.
+
+### Config File Format (V2)
+
+```json
+{
+  "activeProfile": "work",
+  "profiles": {
+    "work": {
+      "apiKey": "nxs_...",
+      "baseUrl": "https://api.nexusgpt.io",
+      "orgName": "Acme Corp",
+      "orgId": "org_..."
+    },
+    "personal": {
+      "apiKey": "nxs_...",
+      "orgName": "My Startup"
+    }
+  }
+}
+```
+
+### .nexusrc Format
+
+```json
+{ "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`](../sdk/README.md)                                         |
+| Product Documentation | [`packages/docs`](../docs/)                                                    |
+| Claude Code Skills    | [`packages/claude-code-skills`](../claude-code-skills/)                        |
+| API Reference         | `https://api.nexusgpt.io/api/public/v1`                                        |
+| Dashboard             | [app.nexusgpt.io](https://app.nexusgpt.io)                                     |
+| CLI Command Reference | [docs/command-reference.md](docs/command-reference.md)                         |
+| Input/Output Guide    | [docs/input-output-patterns.md](docs/input-output-patterns.md)                 |
+| Common Gotchas        | [docs/gotchas.md](docs/gotchas.md)                                             |
+| Recipes               | [docs/recipes.md](docs/recipes.md)                                             |
+| Report Issues         | `nexus ticket create --type BUG --title "..." --description "..."`             |
+| Request Features      | `nexus ticket create --type FEATURE_REQUEST --title "..." --description "..."` |
+
+---
+
+## License
+
+[MIT](LICENSE)