@agent-nexus/cli 0.1.5 → 0.1.6

package/README.md

@@ -0,0 +1,667 @@
+# @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`                                                 |
+
+---
+
+## 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                         |
+| `-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`               |
+| `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` `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 |
+| [`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`        | API key and base URL (written by `nexus auth login`) | `0600`      |
+| `~/.nexus-mcp/version-check.json` | Update check cache (auto-managed, checked once/day)  | `0600`      |
+
+The `~/.nexus-mcp/` directory is created with `0700` permissions. This path is shared with the [`@nexus/mcp-server`](../mcp-server/) package, so logging in via the CLI also authenticates the MCP server.
+
+### Config File Format
+
+```json
+{
+  "apiKey": "nxs_your_api_key_here",
+  "baseUrl": "https://api.nexusgpt.io"
+}
+```
+
+---
+
+## 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)

package/dist/index.js

@@ -38,6 +38,7 @@ var output_exports = {};
 __export(output_exports, {
   color: () => color,
   isJsonMode: () => isJsonMode,
+  printContextBanner: () => printContextBanner,
   printList: () => printList,
   printPaginationMeta: () => printPaginationMeta,
   printRecord: () => printRecord,
@@ -116,6 +117,13 @@ function printPaginationMeta(meta) {
 ${parts.join(" \xB7 ")}`));
   }
 }
+function printContextBanner(resolved) {
+  if (_jsonMode) return;
+  if (!process.stderr.isTTY) return;
+  const orgPart = resolved.profile.orgName ? ` (${resolved.profile.orgName})` : "";
+  const line = `\u25B8 ${resolved.name}${orgPart} \xB7 ${SOURCE_LABELS[resolved.source]}`;
+  process.stderr.write(color.dim(line) + "\n");
+}
 function printList(data, meta, columns) {
   if (_jsonMode) {
     console.log(JSON.stringify({ data, meta }, null, 2));
@@ -126,7 +134,7 @@ function printList(data, meta, columns) {
     printPaginationMeta(meta);
   }
 }
-var _jsonMode, NO_COLOR2, color;
+var _jsonMode, NO_COLOR2, color, SOURCE_LABELS;
 var init_output = __esm({
   "src/output.ts"() {
     "use strict";
@@ -142,6 +150,14 @@ var init_output = __esm({
       yellow: (t) => c2("33", t),
       cyan: (t) => c2("36", t)
     };
+    SOURCE_LABELS = {
+      flag: "flag override",
+      env: "env",
+      directory: ".nexusrc",
+      active: "active",
+      default: "default",
+      override: "api-key override"
+    };
   }
 });
 
@@ -150,7 +166,7 @@ var require_package = __commonJS({
   "package.json"(exports2, module2) {
     module2.exports = {
       name: "@agent-nexus/cli",
-      version: "0.1.5",
+      version: "0.1.6",
       description: "Official CLI for the Nexus AI agent platform.",
       license: "MIT",
       keywords: [
@@ -240,12 +256,32 @@ var URL_MAP = {
 };
 var CONFIG_DIR = import_node_path.default.join(import_node_os.default.homedir(), ".nexus-mcp");
 var CONFIG_FILE = import_node_path.default.join(CONFIG_DIR, "config.json");
+var NEXUSRC_FILENAME = ".nexusrc";
+var PROFILE_NAME_RE = /^[a-z0-9][a-z0-9_-]{0,31}$/;
 function loadConfig() {
   try {
     const raw = import_node_fs.default.readFileSync(CONFIG_FILE, "utf-8");
-    return JSON.parse(raw);
+    const parsed = JSON.parse(raw);
+    if ("profiles" in parsed && typeof parsed.profiles === "object") {
+      return parsed;
+    }
+    const v1 = parsed;
+    if (v1.apiKey) {
+      const migrated = {
+        activeProfile: "default",
+        profiles: {
+          default: {
+            apiKey: v1.apiKey,
+            ...v1.baseUrl ? { baseUrl: v1.baseUrl } : {}
+          }
+        }
+      };
+      saveConfig(migrated);
+      return migrated;
+    }
+    return emptyConfig();
   } catch {
-    return {};
+    return emptyConfig();
   }
 }
 function saveConfig(config) {
@@ -260,27 +296,159 @@ function clearConfig() {
   } catch {
   }
 }
+function emptyConfig() {
+  return { activeProfile: "", profiles: {} };
+}
+function getProfile(name) {
+  return loadConfig().profiles[name];
+}
+function saveProfile(name, profile) {
+  const config = loadConfig();
+  config.profiles[name] = profile;
+  if (!config.activeProfile || Object.keys(config.profiles).length === 1) {
+    config.activeProfile = name;
+  }
+  saveConfig(config);
+}
+function removeProfile(name) {
+  const config = loadConfig();
+  if (!(name in config.profiles)) return false;
+  delete config.profiles[name];
+  if (config.activeProfile === name) {
+    const remaining = Object.keys(config.profiles);
+    config.activeProfile = remaining[0] ?? "";
+  }
+  saveConfig(config);
+  return true;
+}
+function setActiveProfile(name) {
+  const config = loadConfig();
+  if (!(name in config.profiles)) {
+    const available = Object.keys(config.profiles).join(", ");
+    throw new Error(
+      `Profile "${name}" not found.` + (available ? ` Available: ${available}. Run: nexus auth list` : " Run: nexus auth login")
+    );
+  }
+  config.activeProfile = name;
+  saveConfig(config);
+}
+function listProfiles() {
+  const config = loadConfig();
+  return { profiles: config.profiles, activeProfile: config.activeProfile };
+}
+function validateProfileName(name) {
+  if (!PROFILE_NAME_RE.test(name)) {
+    return `Invalid profile name "${name}". Use lowercase letters, numbers, hyphens, underscores (max 32 chars, must start with alphanumeric).`;
+  }
+  return null;
+}
+function slugifyProfileName(input) {
+  return input.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 32) || "default";
+}
+function findNexusRc(startDir = process.cwd()) {
+  let dir = import_node_path.default.resolve(startDir);
+  const root = import_node_path.default.parse(dir).root;
+  while (true) {
+    const rcPath = import_node_path.default.join(dir, NEXUSRC_FILENAME);
+    try {
+      const raw = import_node_fs.default.readFileSync(rcPath, "utf-8");
+      const parsed = JSON.parse(raw);
+      if (parsed.profile && typeof parsed.profile === "string") {
+        return { profile: parsed.profile, rcPath };
+      }
+    } catch {
+    }
+    if (dir === root) break;
+    dir = import_node_path.default.dirname(dir);
+  }
+  return null;
+}
+function writeNexusRc(dir, profile) {
+  const rcPath = import_node_path.default.join(dir, NEXUSRC_FILENAME);
+  import_node_fs.default.writeFileSync(rcPath, JSON.stringify({ profile }, null, 2) + "\n");
+}
+function removeNexusRc(dir) {
+  const rcPath = import_node_path.default.join(dir, NEXUSRC_FILENAME);
+  try {
+    import_node_fs.default.unlinkSync(rcPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function resolveProfile(opts) {
+  const directKey = opts?.apiKey || process.env.NEXUS_API_KEY;
+  if (directKey) {
+    return {
+      name: "override",
+      profile: {
+        apiKey: directKey,
+        baseUrl: opts?.baseUrl || process.env.NEXUS_BASE_URL
+      },
+      source: "override"
+    };
+  }
+  const config = loadConfig();
+  const profileNames = Object.keys(config.profiles);
+  const lookup = (name, source, rcPath) => {
+    const profile = config.profiles[name];
+    if (!profile) {
+      const available = profileNames.join(", ");
+      const sourceHint = source === "flag" ? `(from --profile flag)` : source === "env" ? `(from NEXUS_PROFILE env)` : source === "directory" ? `(from .nexusrc at ${rcPath})` : source === "active" ? `(active profile)` : `(default profile)`;
+      throw new Error(
+        `Profile "${name}" ${sourceHint} not found.` + (available ? ` Available: ${available}. Run: nexus auth list` : " No profiles configured. Run: nexus auth login")
+      );
+    }
+    return { name, profile, source, rcPath };
+  };
+  if (opts?.profile) {
+    return lookup(opts.profile, "flag");
+  }
+  if (process.env.NEXUS_PROFILE) {
+    return lookup(process.env.NEXUS_PROFILE, "env");
+  }
+  const rc = findNexusRc();
+  if (rc) {
+    return lookup(rc.profile, "directory", rc.rcPath);
+  }
+  if (config.activeProfile && config.profiles[config.activeProfile]) {
+    return lookup(config.activeProfile, "active");
+  }
+  if (config.profiles["default"]) {
+    return lookup("default", "default");
+  }
+  if (profileNames.length > 0) {
+    throw new Error(
+      `No active profile set. Available: ${profileNames.join(", ")}.
+  Run: nexus auth switch <profile>`
+    );
+  }
+  throw new Error("No profiles configured. Run:\n  nexus auth login");
+}
+function resolveApiKey(override) {
+  if (override) return override;
+  return resolveProfile().profile.apiKey;
+}
 function resolveBaseUrl(override) {
   if (override) return override;
   if (process.env.NEXUS_BASE_URL) return process.env.NEXUS_BASE_URL;
-  const config = loadConfig();
-  if (config.baseUrl) return config.baseUrl;
+  try {
+    const resolved = resolveProfile();
+    if (resolved.profile.baseUrl) return resolved.profile.baseUrl;
+  } catch {
+  }
   const env = process.env.NEXUS_ENV ?? "production";
   return URL_MAP[env] ?? URL_MAP.production;
 }
-function resolveApiKey(override) {
-  if (override) return override;
-  if (process.env.NEXUS_API_KEY) return process.env.NEXUS_API_KEY;
-  const config = loadConfig();
-  if (config.apiKey) return config.apiKey;
-  throw new Error("No API key found. Set NEXUS_API_KEY or run:\n  nexus auth login");
-}
 
 // src/client.ts
+var _lastResolved = null;
 function createClient(opts) {
+  const resolved = resolveProfile(opts);
+  _lastResolved = resolved;
   return new import_sdk.NexusClient({
-    apiKey: resolveApiKey(opts?.apiKey),
-    baseUrl: resolveBaseUrl(opts?.baseUrl)
+    apiKey: resolved.profile.apiKey,
+    baseUrl: resolved.profile.baseUrl ?? resolveBaseUrl(opts?.baseUrl)
   });
 }
 
@@ -861,20 +1029,21 @@ var import_promises = __toESM(require("readline/promises"));
 init_output();
 var SETTINGS_URL = "https://app.nexusgpt.io/app/settings/api-keys";
 function registerAuthCommands(program2) {
-  const auth = program2.command("auth").description("Manage authentication");
-  auth.command("login").description("Authenticate with the Nexus API").option("--api-key <key>", "API key (skip interactive prompt)").option("--env <env>", "Environment: dev or production", "production").addHelpText(
+  const auth = program2.command("auth").description("Manage authentication and profiles");
+  auth.command("login").description("Authenticate with the Nexus API and create a profile").option("--api-key <key>", "API key (skip interactive prompt)").option("--profile <name>", "Profile name to save as").option("--env <env>", "Environment: dev or production", "production").addHelpText(
     "after",
     `
 Examples:
   $ nexus auth login
   $ nexus auth login --api-key nxs_abc123
+  $ nexus auth login --profile work --api-key nxs_abc123
   $ nexus auth login --env dev`
   ).action(async (opts) => {
-    const config = loadConfig();
+    let baseUrl;
     if (opts.env === "dev") {
-      config.baseUrl = "http://localhost:3001";
+      baseUrl = "http://localhost:3001";
     }
-    const baseUrl = config.baseUrl ?? resolveBaseUrl();
+    const resolvedBaseUrl = baseUrl ?? resolveBaseUrl();
     let apiKey = opts.apiKey;
     if (!apiKey) {
       console.log(`Opening ${color.cyan(SETTINGS_URL)} ...`);
@@ -900,31 +1069,228 @@ Examples:
       return;
     }
     console.log("Validating...");
-    const res = await fetch(`${baseUrl}/api/public/v1/agents?limit=1`, {
+    const validateRes = await fetch(`${resolvedBaseUrl}/api/public/v1/agents?limit=1`, {
       headers: { "api-key": apiKey, Accept: "application/json" }
     });
-    if (!res.ok) {
+    if (!validateRes.ok) {
       console.error(
-        color.red("Error:") + ` Validation failed (HTTP ${res.status}). Check your key and try again.`
+        color.red("Error:") + ` Validation failed (HTTP ${validateRes.status}). Check your key and try again.`
       );
       process.exitCode = 1;
       return;
     }
-    config.apiKey = apiKey;
-    if (opts.env === "dev") config.baseUrl = "http://localhost:3001";
-    saveConfig(config);
-    printSuccess("Logged in successfully.", {
+    let orgName;
+    let orgId;
+    try {
+      const meRes = await fetch(`${resolvedBaseUrl}/api/public/v1/me`, {
+        headers: { "api-key": apiKey, Accept: "application/json" }
+      });
+      if (meRes.ok) {
+        const meJson = await meRes.json();
+        if (meJson.data) {
+          orgName = meJson.data.orgName;
+          orgId = meJson.data.orgId;
+        }
+      }
+    } catch {
+    }
+    if (orgName) {
+      console.log(`Organization: ${color.cyan(orgName)}`);
+    }
+    let profileName = opts.profile;
+    if (!profileName) {
+      const suggested = orgName ? slugifyProfileName(orgName) : "default";
+      const rl = import_promises.default.createInterface({ input: import_node_process.stdin, output: import_node_process.stdout });
+      try {
+        const answer = (await rl.question(`Profile name [${suggested}]: `)).trim();
+        profileName = answer || suggested;
+      } finally {
+        rl.close();
+      }
+    }
+    const nameError = validateProfileName(profileName);
+    if (nameError) {
+      console.error(color.red("Error:") + " " + nameError);
+      process.exitCode = 1;
+      return;
+    }
+    const existing = getProfile(profileName);
+    if (existing) {
+      const existingLabel = existing.orgName ? ` (${existing.orgName})` : "";
+      const rl = import_promises.default.createInterface({ input: import_node_process.stdin, output: import_node_process.stdout });
+      try {
+        const answer = (await rl.question(
+          `Profile "${profileName}"${existingLabel} already exists. Overwrite? [y/N]: `
+        )).trim();
+        if (answer.toLowerCase() !== "y") {
+          console.log("Aborted.");
+          return;
+        }
+      } finally {
+        rl.close();
+      }
+    }
+    saveProfile(profileName, {
+      apiKey,
+      ...baseUrl ? { baseUrl } : {},
+      ...orgName ? { orgName } : {},
+      ...orgId ? { orgId } : {}
+    });
+    printSuccess(`Saved profile "${profileName}".`, {
+      ...orgName ? { organization: orgName } : {},
+      profile: profileName,
       config: "~/.nexus-mcp/config.json"
     });
+    const { profiles } = listProfiles();
+    if (Object.keys(profiles).length > 1) {
+      console.log(
+        "\n" + color.dim("Tip: You have multiple profiles. Consider pinning directories:") + "\n" + color.dim(`  nexus auth pin ${profileName}    (in your project directory)`)
+      );
+    }
+  });
+  auth.command("logout").description("Remove stored credentials").argument("[name]", "Specific profile to remove (default: active profile)").option("--all", "Remove all profiles").addHelpText(
+    "after",
+    `
+Examples:
+  $ nexus auth logout           # removes active profile
+  $ nexus auth logout work      # removes "work" profile
+  $ nexus auth logout --all     # removes all profiles`
+  ).action((name, opts) => {
+    if (opts.all) {
+      clearConfig();
+      printSuccess("All profiles removed.");
+      return;
+    }
+    const { activeProfile, profiles } = listProfiles();
+    const target = name ?? activeProfile;
+    if (!target) {
+      console.error(color.red("Error:") + " No active profile. Run: nexus auth login");
+      process.exitCode = 1;
+      return;
+    }
+    if (!removeProfile(target)) {
+      console.error(color.red("Error:") + ` Profile "${target}" not found. Run: nexus auth list`);
+      process.exitCode = 1;
+      return;
+    }
+    const remaining = Object.keys(profiles).filter((p) => p !== target);
+    if (remaining.length === 0) {
+      printSuccess(`Removed profile "${target}". No profiles remaining. Run: nexus auth login`);
+    } else {
+      const { activeProfile: newActive } = listProfiles();
+      printSuccess(`Removed profile "${target}".`, {
+        remaining: remaining.join(", "),
+        ...newActive ? { active: newActive } : {}
+      });
+    }
+  });
+  auth.command("switch").description("Switch the active profile").argument("<name>", "Profile name to activate").addHelpText(
+    "after",
+    `
+Examples:
+  $ nexus auth switch work
+  $ nexus auth switch personal`
+  ).action((name) => {
+    try {
+      setActiveProfile(name);
+    } catch (err) {
+      console.error(color.red("Error:") + " " + err.message);
+      process.exitCode = 1;
+      return;
+    }
+    const profile = getProfile(name);
+    const orgPart = profile?.orgName ? ` (${profile.orgName})` : "";
+    printSuccess(`Switched to "${name}"${orgPart}.`);
+  });
+  auth.command("list").description("List all saved profiles").addHelpText(
+    "after",
+    `
+Examples:
+  $ nexus auth list`
+  ).action(() => {
+    const { profiles, activeProfile } = listProfiles();
+    const names = Object.keys(profiles);
+    if (names.length === 0) {
+      console.log(color.dim("No profiles. Run: nexus auth login"));
+      return;
+    }
+    const rows = names.map((name) => ({
+      marker: name === activeProfile ? "\u25B8" : " ",
+      name,
+      orgName: profiles[name].orgName ?? color.dim("\u2014"),
+      baseUrl: profiles[name].baseUrl ?? "https://api.nexusgpt.io"
+    }));
+    printTable(rows, [
+      { key: "marker", label: " ", width: 2 },
+      { key: "name", label: "PROFILE" },
+      { key: "orgName", label: "ORGANIZATION" },
+      { key: "baseUrl", label: "BASE URL" }
+    ]);
+  });
+  auth.command("pin").description("Pin the current directory to a profile via .nexusrc").argument("<profile>", "Profile name to pin").addHelpText(
+    "after",
+    `
+Examples:
+  $ nexus auth pin work`
+  ).action((profileName) => {
+    const profile = getProfile(profileName);
+    if (!profile) {
+      const { profiles } = listProfiles();
+      const available = Object.keys(profiles).join(", ");
+      console.error(
+        color.red("Error:") + ` Profile "${profileName}" not found.` + (available ? ` Available: ${available}` : " Run: nexus auth login")
+      );
+      process.exitCode = 1;
+      return;
+    }
+    writeNexusRc(process.cwd(), profileName);
+    const orgPart = profile.orgName ? ` (${profile.orgName})` : "";
+    printSuccess(`Pinned this directory to "${profileName}"${orgPart}.`, {
+      file: ".nexusrc"
+    });
+    console.log(color.dim("\n  Tip: Consider adding .nexusrc to your .gitignore"));
+  });
+  auth.command("unpin").description("Remove .nexusrc from the current directory").addHelpText(
+    "after",
+    `
+Examples:
+  $ nexus auth unpin`
+  ).action(() => {
+    if (!removeNexusRc(process.cwd())) {
+      console.error(color.red("Error:") + " No .nexusrc found in current directory.");
+      process.exitCode = 1;
+      return;
+    }
+    printSuccess("Removed .nexusrc from current directory.");
   });
-  auth.command("logout").description("Remove stored credentials").addHelpText(
+  auth.command("status").description("Show resolved profile and how it was determined").addHelpText(
     "after",
     `
 Examples:
-  $ nexus auth logout`
+  $ nexus auth status`
   ).action(() => {
-    clearConfig();
-    printSuccess("Logged out. Credentials removed from ~/.nexus-mcp/config.json");
+    try {
+      const resolved = resolveProfile(program2.optsWithGlobals());
+      const sourceExplanation = {
+        flag: "--profile flag",
+        env: "NEXUS_PROFILE environment variable",
+        directory: `.nexusrc at ${resolved.rcPath}`,
+        active: "active profile in config",
+        default: 'fallback to "default" profile',
+        override: "--api-key flag or NEXUS_API_KEY env"
+      };
+      const orgPart = resolved.profile.orgName ? ` (${resolved.profile.orgName})` : "";
+      console.log(
+        `Using profile ${color.cyan(`"${resolved.name}"`)}${orgPart} \u2014 ${color.dim(sourceExplanation[resolved.source])}`
+      );
+      console.log(
+        `  ${color.dim("key:")} ${resolved.profile.apiKey.slice(0, 8)}...${resolved.profile.apiKey.slice(-4)}`
+      );
+      console.log(`  ${color.dim("api:")} ${resolved.profile.baseUrl ?? resolveBaseUrl()}`);
+    } catch (err) {
+      console.error(color.red("Error:") + " " + err.message);
+      process.exitCode = 1;
+    }
   });
   auth.command("whoami").description("Show current authentication status").addHelpText(
     "after",
@@ -933,10 +1299,10 @@ Examples:
   $ nexus auth whoami`
   ).action(async () => {
     try {
-      const apiKey = resolveApiKey();
-      const baseUrl = resolveBaseUrl();
+      const resolved = resolveProfile(program2.optsWithGlobals());
+      const baseUrl = resolved.profile.baseUrl ?? resolveBaseUrl();
       const res = await fetch(`${baseUrl}/api/public/v1/agents?limit=1`, {
-        headers: { "api-key": apiKey, Accept: "application/json" }
+        headers: { "api-key": resolved.profile.apiKey, Accept: "application/json" }
       });
       if (!res.ok) {
         console.error(
@@ -946,8 +1312,10 @@ Examples:
         return;
       }
       printSuccess("Authenticated.", {
+        profile: resolved.name,
+        ...resolved.profile.orgName ? { organization: resolved.profile.orgName } : {},
         api: baseUrl,
-        key: apiKey.slice(0, 8) + "..." + apiKey.slice(-4)
+        key: resolved.profile.apiKey.slice(0, 8) + "..." + resolved.profile.apiKey.slice(-4)
       });
     } catch (err) {
       console.error(color.red("Error:") + " Not logged in. Run: nexus auth login");
@@ -3353,47 +3721,63 @@ function formatUpdateMessage(current, latest) {
   IMPORTANT: You MUST update before running any other nexus commands. Results from an outdated CLI may be incorrect.
 `;
 }
+async function autoUpdate(currentVersion) {
+  try {
+    const cache = loadCache();
+    let latest = null;
+    if (cache && Date.now() - cache.lastChecked < CHECK_INTERVAL_MS) {
+      latest = cache.latestVersion;
+    } else {
+      latest = await fetchLatestVersion();
+      if (latest) {
+        saveCache({ lastChecked: Date.now(), latestVersion: latest });
+      }
+    }
+    if (!latest || compareSemver(currentVersion, latest) >= 0) {
+      return null;
+    }
+    const { execSync: execSync2 } = await import("child_process");
+    process.stderr.write(`
+  Auto-updating: ${currentVersion} \u2192 ${latest}\u2026
+`);
+    execSync2(`npm install -g ${PACKAGE_NAME}@latest`, {
+      stdio: "inherit"
+    });
+    return `
+  Successfully auto-updated to ${latest}.
+`;
+  } catch {
+    return formatUpdateMessage(currentVersion, loadCache()?.latestVersion ?? "latest");
+  }
+}
 
 // src/commands/upgrade.ts
 var PACKAGE_NAME2 = "@agent-nexus/cli";
 function registerUpgradeCommand(program2) {
   const currentVersion = require_package().version;
-  program2.command("upgrade").description("Upgrade the Nexus CLI to the latest version").addHelpText(
-    "after",
-    `
+  program2.command("upgrade").description("Upgrade the Nexus CLI to the latest version").addHelpText("after", `
 Examples:
-  $ nexus upgrade`
-  ).action(async () => {
+  $ nexus upgrade`).action(async () => {
     process.stderr.write(`Current version: ${color.cyan(currentVersion)}
 `);
     process.stderr.write("Checking for updates\u2026\n");
     const latest = await fetchLatestVersion();
     if (!latest) {
-      process.stderr.write(
-        color.red("Failed to check for updates. Please try again later.\n")
-      );
+      process.stderr.write(color.red("Failed to check for updates. Please try again later.\n"));
       process.exitCode = 1;
       return;
     }
     if (compareSemver(currentVersion, latest) >= 0) {
-      printSuccess(
-        `Already up-to-date (${currentVersion}).`,
-        { version: currentVersion }
-      );
+      printSuccess(`Already up-to-date (${currentVersion}).`, { version: currentVersion });
       return;
     }
-    process.stderr.write(
-      `Upgrading ${color.yellow(currentVersion)} \u2192 ${color.green(latest)}\u2026
-`
-    );
+    process.stderr.write(`Upgrading ${color.yellow(currentVersion)} \u2192 ${color.green(latest)}\u2026
+`);
     try {
       (0, import_node_child_process2.execSync)(`npm install -g ${PACKAGE_NAME2}@latest`, {
         stdio: "inherit"
       });
-      printSuccess(
-        `Successfully upgraded to ${latest}.`,
-        { from: currentVersion, to: latest }
-      );
+      printSuccess(`Successfully upgraded to ${latest}.`, { from: currentVersion, to: latest });
     } catch {
       process.stderr.write(
         color.red(
@@ -4182,9 +4566,30 @@ Examples:
 // src/index.ts
 init_output();
 var { version: VERSION } = require_package();
-var program = new import_commander.Command().name("nexus").description("Official CLI for the Nexus AI agent platform").version(VERSION, "-v, --version").option("--json", "Output as JSON").option("--api-key <key>", "Override API key for this invocation").option("--base-url <url>", "Override API base URL").hook("preAction", (thisCommand) => {
+var program = new import_commander.Command().name("nexus").description("Official CLI for the Nexus AI agent platform").version(VERSION, "-v, --version").option("--json", "Output as JSON").option("--api-key <key>", "Override API key for this invocation").option("--base-url <url>", "Override API base URL").option("--profile <name>", "Use a specific named profile").option("--no-auto-update", "Disable automatic updates when a new version is detected").hook("preAction", (thisCommand) => {
   const opts = thisCommand.optsWithGlobals();
   if (opts.json) setJsonMode(true);
+  const cmdName = thisCommand.name();
+  const skipBanner = [
+    "auth",
+    "upgrade",
+    "version",
+    "login",
+    "logout",
+    "whoami",
+    "switch",
+    "list",
+    "pin",
+    "unpin",
+    "status"
+  ].includes(cmdName);
+  if (!skipBanner && !isJsonMode()) {
+    try {
+      const resolved = resolveProfile(opts);
+      printContextBanner(resolved);
+    } catch {
+    }
+  }
 });
 program.addHelpText("before", getBanner(VERSION));
 program.configureHelp({
@@ -4217,10 +4622,22 @@ if (process.argv.length <= 2) {
   program.help();
 }
 program.parseAsync(process.argv).then(async () => {
-  const updateMsg = await checkForUpdate(VERSION);
-  if (updateMsg && !isJsonMode()) {
-    const { color: color2 } = await Promise.resolve().then(() => (init_output(), output_exports));
-    process.stderr.write(color2.yellow(updateMsg));
+  if (isJsonMode()) return;
+  const ranCommand = process.argv[2];
+  if (ranCommand === "upgrade") return;
+  const opts = program.opts();
+  if (opts.autoUpdate) {
+    const msg = await autoUpdate(VERSION);
+    if (msg) {
+      const { color: color2 } = await Promise.resolve().then(() => (init_output(), output_exports));
+      process.stderr.write(color2.green(msg));
+    }
+  } else {
+    const updateMsg = await checkForUpdate(VERSION);
+    if (updateMsg) {
+      const { color: color2 } = await Promise.resolve().then(() => (init_output(), output_exports));
+      process.stderr.write(color2.yellow(updateMsg));
+    }
   }
 }).catch((err) => {
   process.exitCode = handleError(err);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-nexus/cli",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "Official CLI for the Nexus AI agent platform.",
   "license": "MIT",
   "keywords": [
@@ -30,7 +30,7 @@
   },
   "dependencies": {
     "commander": "^13.0.0",
-    "@agent-nexus/sdk": "0.1.3"
+    "@agent-nexus/sdk": "0.1.4"
   },
   "devDependencies": {
     "@types/node": "24.6.2",