@agent-nexus/cli 0.1.3 → 0.1.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +667 -0
  2. package/dist/index.js +591 -117
  3. package/package.json +2 -2
package/README.md ADDED
@@ -0,0 +1,667 @@
1
+ # @agent-nexus/cli
2
+
3
+ Official CLI for the [Nexus](https://nexusgpt.io) AI agent platform. Manage agents, workflows, deployments, knowledge bases, and more from your terminal.
4
+
5
+ - Wraps the full [Nexus Public API v1](../sdk)
6
+ - 24 command groups, 120+ subcommands
7
+ - Table, record, and JSON output modes
8
+ - Pipe-friendly: stdin input, `--json` output, composable with `jq`
9
+ - Zero config after `nexus auth login`
10
+ - Node.js 18+
11
+
12
+ > **Status: BETA** -- The CLI surface is stable but may evolve before 1.0.
13
+
14
+ ---
15
+
16
+ ## Table of Contents
17
+
18
+ - [Installation](#installation)
19
+ - [Authentication](#authentication)
20
+ - [Quick Start](#quick-start)
21
+ - [Global Options](#global-options)
22
+ - [Input Patterns](#input-patterns)
23
+ - [Output Modes](#output-modes)
24
+ - [Commands](#commands)
25
+ - [Common Patterns](#common-patterns)
26
+ - [SDK Cross-Reference](#sdk-cross-reference)
27
+ - [Error Handling](#error-handling)
28
+ - [Troubleshooting](#troubleshooting)
29
+ - [Configuration Files](#configuration-files)
30
+ - [Related Resources](#related-resources)
31
+ - [License](#license)
32
+
33
+ ---
34
+
35
+ ## Installation
36
+
37
+ ```bash
38
+ # Install globally
39
+ npm install -g @agent-nexus/cli
40
+
41
+ # Or with pnpm
42
+ pnpm add -g @agent-nexus/cli
43
+
44
+ # Or with yarn
45
+ yarn global add @agent-nexus/cli
46
+ ```
47
+
48
+ Run a one-off command without installing:
49
+
50
+ ```bash
51
+ npx @agent-nexus/cli agent list
52
+ ```
53
+
54
+ Verify the installation:
55
+
56
+ ```bash
57
+ nexus --version
58
+ ```
59
+
60
+ Upgrade to the latest version:
61
+
62
+ ```bash
63
+ nexus upgrade
64
+ ```
65
+
66
+ > 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.
67
+
68
+ ---
69
+
70
+ ## Authentication
71
+
72
+ ### Interactive Login
73
+
74
+ ```bash
75
+ nexus auth login
76
+ ```
77
+
78
+ 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.
79
+
80
+ ### Non-Interactive Login
81
+
82
+ For CI/CD or scripting:
83
+
84
+ ```bash
85
+ # Via flag
86
+ nexus auth login --api-key nxs_abc123
87
+
88
+ # Via environment variable (no login needed)
89
+ export NEXUS_API_KEY=nxs_abc123
90
+ ```
91
+
92
+ ### Verify Authentication
93
+
94
+ ```bash
95
+ nexus auth whoami
96
+ ```
97
+
98
+ Prints the API base URL and a masked version of your key (e.g., `nxs_abc1...3def`).
99
+
100
+ ### Logout
101
+
102
+ ```bash
103
+ nexus auth logout
104
+ ```
105
+
106
+ Removes stored credentials from `~/.nexus-mcp/config.json`.
107
+
108
+ ### API Key Resolution
109
+
110
+ The CLI resolves the API key in this order (first match wins):
111
+
112
+ | Priority | Source | Example |
113
+ | -------- | ----------------------- | ------------------------------------ |
114
+ | 1 | `--api-key` flag | `nexus agent list --api-key nxs_...` |
115
+ | 2 | `NEXUS_API_KEY` env var | `export NEXUS_API_KEY=nxs_...` |
116
+ | 3 | Config file | Written by `nexus auth login` |
117
+
118
+ ### Base URL Resolution
119
+
120
+ | Priority | Source | Default |
121
+ | -------- | ------------------------ | ------------------------------------------------------------------------- |
122
+ | 1 | `--base-url` flag | |
123
+ | 2 | `NEXUS_BASE_URL` env var | |
124
+ | 3 | Config file | |
125
+ | 4 | `NEXUS_ENV` env var | `production` = `https://api.nexusgpt.io`, `dev` = `http://localhost:3001` |
126
+ | 5 | Default | `https://api.nexusgpt.io` |
127
+
128
+ ---
129
+
130
+ ## Quick Start
131
+
132
+ A complete walkthrough: create an agent, give it a knowledge base, deploy it, and test it.
133
+
134
+ ```bash
135
+ # 1. Authenticate
136
+ nexus auth login
137
+
138
+ # 2. Create an agent
139
+ nexus agent create \
140
+ --first-name "Support" \
141
+ --last-name "Bot" \
142
+ --role "Customer Support" \
143
+ --prompt "You are a helpful customer support agent. Answer questions using the knowledge base."
144
+
145
+ # 3. Upload a document to the knowledge base
146
+ nexus document upload ./product-faq.pdf
147
+
148
+ # 4. Create a collection (retrieval-augmented generation index)
149
+ nexus collection create --name "Product FAQ"
150
+
151
+ # 5. Attach the document to the collection
152
+ nexus collection attach-documents <collection-id> --document-ids <document-id>
153
+
154
+ # 6. Attach the collection as a tool on the agent
155
+ nexus agent-tool create <agent-id> \
156
+ --type COLLECTION \
157
+ --collection-id <collection-id> \
158
+ --label "FAQ Search"
159
+
160
+ # 7. Deploy the agent as a web widget
161
+ nexus deployment create \
162
+ --name "Support Widget" \
163
+ --type web \
164
+ --agent-id <agent-id>
165
+
166
+ # 8. Test via the emulator
167
+ nexus emulator session create <deployment-id>
168
+ nexus emulator send <deployment-id> <session-id> \
169
+ --text "How do I reset my password?"
170
+ ```
171
+
172
+ > **Tip:** Add `--json` to any command and pipe to `jq` to extract IDs:
173
+ >
174
+ > ```bash
175
+ > AGENT_ID=$(nexus agent create --first-name Bot --last-name Helper --role QA --json | jq -r '.id')
176
+ > ```
177
+
178
+ ---
179
+
180
+ ## Global Options
181
+
182
+ These flags are available on every command:
183
+
184
+ | Flag | Description |
185
+ | ------------------ | ------------------------------------------------- |
186
+ | `--json` | Output results as JSON (for scripting and piping) |
187
+ | `--api-key <key>` | Override the API key for this invocation |
188
+ | `--base-url <url>` | Override the API base URL |
189
+ | `-v, --version` | Print the CLI version and exit |
190
+ | `--help` | Show help for any command or subcommand |
191
+
192
+ ### Environment Variables
193
+
194
+ | Variable | Description |
195
+ | ---------------- | --------------------------------------------------------------- |
196
+ | `NEXUS_API_KEY` | API key (used when `--api-key` flag and config file are absent) |
197
+ | `NEXUS_BASE_URL` | API base URL override |
198
+ | `NEXUS_ENV` | Environment name: `production` (default) or `dev` |
199
+ | `NO_COLOR` | Disable all color output ([no-color.org](https://no-color.org)) |
200
+
201
+ ---
202
+
203
+ ## Input Patterns
204
+
205
+ The CLI offers flexible input for create and update commands.
206
+
207
+ ### The `--body` Flag
208
+
209
+ Most create/update commands accept `--body` for raw JSON input:
210
+
211
+ ```bash
212
+ # Inline JSON
213
+ nexus agent create --body '{"firstName":"Ada","lastName":"Bot","role":"Assistant"}'
214
+
215
+ # From a JSON file
216
+ nexus agent create --body payload.json
217
+
218
+ # From stdin
219
+ cat payload.json | nexus agent create --body -
220
+ echo '{"firstName":"Ada","lastName":"Bot","role":"Assistant"}' | nexus agent create --body -
221
+ ```
222
+
223
+ ### Flag-Over-Body Merge
224
+
225
+ When you use both `--body` and individual flags, **flags take precedence**. The body provides defaults; flags override specific fields:
226
+
227
+ ```bash
228
+ # Body sets firstName and role; --role flag overrides the role field
229
+ nexus agent create \
230
+ --body '{"firstName":"Ada","lastName":"Bot","role":"Assistant"}' \
231
+ --role "Senior Assistant"
232
+ # Result: { firstName: "Ada", lastName: "Bot", role: "Senior Assistant" }
233
+ ```
234
+
235
+ ### File and Stdin Input
236
+
237
+ Flags like `--prompt`, `--content`, and `--description` accept:
238
+
239
+ | Input | Example |
240
+ | ------------ | ---------------------------------------------------------------- |
241
+ | Literal text | `--prompt "You are a helpful agent"` |
242
+ | File path | `--prompt ./system-prompt.md` (auto-detected if the file exists) |
243
+ | Stdin | `--prompt -` (reads from stdin) |
244
+
245
+ ```bash
246
+ # Load a prompt from a markdown file
247
+ nexus agent create --first-name Bot --last-name Helper --role QA --prompt ./prompt.md
248
+
249
+ # Pipe a prompt from another command
250
+ generate-prompt | nexus agent update abc-123 --prompt -
251
+ ```
252
+
253
+ ### Pagination
254
+
255
+ List commands support pagination:
256
+
257
+ ```bash
258
+ nexus agent list --page 2 --limit 50
259
+ ```
260
+
261
+ The pagination footer shows `total`, `page`, and whether `more available`.
262
+
263
+ ---
264
+
265
+ ## Output Modes
266
+
267
+ ### Table (Default for Lists)
268
+
269
+ ```
270
+ ID FIRST NAME STATUS
271
+ ──────────────────────────────────── ─────────────── ──────
272
+ abc-123-def-456 Support Bot ACTIVE
273
+ ghi-789-jkl-012 Sales Agent DRAFT
274
+
275
+ 3 total · page 1 · more available
276
+ ```
277
+
278
+ ### Record (Default for Single Resources)
279
+
280
+ ```
281
+ ID abc-123-def-456
282
+ Name Support Bot
283
+ Role Customer Support
284
+ Status ACTIVE
285
+ Created 2026-03-15T10:30:00.000Z
286
+ ```
287
+
288
+ ### JSON (`--json`)
289
+
290
+ ```bash
291
+ nexus agent list --json
292
+ ```
293
+
294
+ ```json
295
+ {
296
+ "data": [{ "id": "abc-123", "firstName": "Support", "lastName": "Bot", "status": "ACTIVE" }],
297
+ "meta": { "total": 3, "page": 1, "hasMore": true }
298
+ }
299
+ ```
300
+
301
+ ```bash
302
+ nexus agent get abc-123 --json
303
+ ```
304
+
305
+ ```json
306
+ {
307
+ "id": "abc-123",
308
+ "firstName": "Support",
309
+ "lastName": "Bot",
310
+ "role": "Customer Support",
311
+ "status": "ACTIVE"
312
+ }
313
+ ```
314
+
315
+ > **Important:** Always use `--json` when piping output to `jq` or other tools. The default table output is for humans and will break parsers.
316
+
317
+ ### Error Output in JSON Mode
318
+
319
+ When `--json` is active, errors are also returned as JSON:
320
+
321
+ ```json
322
+ {
323
+ "error": {
324
+ "message": "Authentication failed — invalid or missing API key.",
325
+ "hint": "Run \"nexus auth login\" to re-authenticate, or set NEXUS_API_KEY."
326
+ }
327
+ }
328
+ ```
329
+
330
+ ---
331
+
332
+ ## Commands
333
+
334
+ All commands follow the pattern: `nexus <group> <action> [arguments] [options]`
335
+
336
+ ### Core Platform
337
+
338
+ | Command | Subcommands | Description |
339
+ | ---------------------------------------------------------- | ----------------------------------------------------------- | ------------------------- |
340
+ | [`auth`](docs/command-reference.md#nexus-auth) | `login` `logout` `whoami` | Authentication |
341
+ | [`agent`](docs/command-reference.md#nexus-agent) | `list` `get` `create` `update` `delete` `duplicate` | AI agent management |
342
+ | [`agent-tool`](docs/command-reference.md#nexus-agent-tool) | `list` `get` `create` `update` `delete` | Agent tool configurations |
343
+ | [`version`](docs/command-reference.md#nexus-version) | `list` `get` `create` `update` `delete` `restore` `publish` | Prompt version management |
344
+ | [`folder`](docs/command-reference.md#nexus-folder) | `list` `create` `update` `delete` `assign` | Agent folder organization |
345
+ | [`model`](docs/command-reference.md#nexus-model) | `list` | Available AI models |
346
+
347
+ ### Workflows & Execution
348
+
349
+ | Command | Subcommands | Description |
350
+ | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | --------------------------- |
351
+ | [`workflow`](docs/command-reference.md#nexus-workflow) | `list` `get` `create` `update` `delete` `duplicate` `publish` `unpublish` `validate` `test` | Workflow CRUD and lifecycle |
352
+ | [`workflow node`](docs/command-reference.md#nexus-workflow-node) | `create` `get` `update` `delete` `test` `variables` `output-format` `reload-props` | Workflow node operations |
353
+ | [`workflow edge`](docs/command-reference.md#nexus-workflow-edge) | `create` `delete` | Node connections |
354
+ | [`workflow branch`](docs/command-reference.md#nexus-workflow-branch) | `list` `create` `update` `delete` | Branching logic |
355
+ | [`execution`](docs/command-reference.md#nexus-execution) | `list` `get` `graph` `output` `retry` `export` `node-result` | Workflow execution history |
356
+
357
+ ### Knowledge & Documents
358
+
359
+ | Command | Subcommands | Description |
360
+ | ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | --------------------- |
361
+ | [`document`](docs/command-reference.md#nexus-document) | `list` `get` `upload` `create-text` `add-website` `import-google-sheets` `delete` | Knowledge documents |
362
+ | [`collection`](docs/command-reference.md#nexus-collection) | `list` `get` `create` `update` `delete` `search` `documents` `attach-documents` `remove-document` `stats` | Knowledge collections |
363
+
364
+ ### Skills & Tasks
365
+
366
+ | Command | Subcommands | Description |
367
+ | ---------------------------------------------------------------- | ------------------------------------------------- | ---------------------- |
368
+ | [`task`](docs/command-reference.md#nexus-task) | `list` `get` `create` `update` `delete` `execute` | AI task management |
369
+ | [`template`](docs/command-reference.md#nexus-template) | `list` `get` `create` `upload` `generate` | Document templates |
370
+ | [`external-tool`](docs/command-reference.md#nexus-external-tool) | `list` `get` `create` `update` `delete` `test` | OpenAPI external tools |
371
+
372
+ ### Deployment & Testing
373
+
374
+ | Command | Subcommands | Description |
375
+ | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------ | --------------------------------- |
376
+ | [`deployment`](docs/command-reference.md#nexus-deployment) | `list` `get` `create` `update` `delete` `duplicate` `stats` `embed-config` `embed-config-update` | Agent deployments |
377
+ | [`deployment folder`](docs/command-reference.md#nexus-deployment-folder) | `list` `create` `update` `delete` `assign` | Deployment folder organization |
378
+ | [`emulator`](docs/command-reference.md#nexus-emulator) | `send` | Send messages to test deployments |
379
+ | [`emulator session`](docs/command-reference.md#nexus-emulator-session) | `create` `list` `get` `delete` | Emulator session management |
380
+ | [`emulator scenario`](docs/command-reference.md#nexus-emulator-scenario) | `save` `list` `get` `replay` `delete` | Save and replay test scenarios |
381
+
382
+ ### Marketplace & Discovery
383
+
384
+ | Command | Subcommands | Description |
385
+ | ---------------------------------------------- | ------------------------------------------------------------------------ | -------------------------- |
386
+ | [`tool`](docs/command-reference.md#nexus-tool) | `search` `get` `credentials` `connect` `resolve-options` `skills` `test` | Marketplace tool discovery |
387
+
388
+ ### Analytics & Operations
389
+
390
+ | Command | Subcommands | Description |
391
+ | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | -------------------------- |
392
+ | [`analytics`](docs/command-reference.md#nexus-analytics) | `overview` `feedback` `export` | Organization analytics |
393
+ | [`eval`](docs/command-reference.md#nexus-eval) | (subgroups: `session`, `dataset`, `execute`, `judge`, `results`, `formats`, `judges`) | AI task evaluation |
394
+ | [`ticket`](docs/command-reference.md#nexus-ticket) | `list` `get` `create` `update` `comment` `comments` | Bug and feature tracking |
395
+ | [`phone-number`](docs/command-reference.md#nexus-phone-number) | `search` `buy` `list` `get` `release` | Phone number management |
396
+ | [`prompt-assistant`](docs/command-reference.md#nexus-prompt-assistant) | `chat` `get-thread` `delete-thread` | AI-assisted prompt writing |
397
+
398
+ ### Utility
399
+
400
+ | Command | Subcommands | Description |
401
+ | ---------------------------------------------------- | ------------- | ------------------------------ |
402
+ | [`api`](docs/command-reference.md#nexus-api) | (passthrough) | Call any API endpoint directly |
403
+ | [`upgrade`](docs/command-reference.md#nexus-upgrade) | (self-update) | Upgrade the CLI to latest |
404
+
405
+ > **Full reference:** See [docs/command-reference.md](docs/command-reference.md) for complete documentation of every command, option, and example.
406
+
407
+ ---
408
+
409
+ ## Common Patterns
410
+
411
+ ### Extract IDs with `jq`
412
+
413
+ ```bash
414
+ # Get the ID of a newly created agent
415
+ AGENT_ID=$(nexus agent create \
416
+ --first-name Bot --last-name Helper --role QA --json | jq -r '.id')
417
+ echo "Created agent: $AGENT_ID"
418
+ ```
419
+
420
+ ### Pipe JSON Output
421
+
422
+ ```bash
423
+ # List all active agent IDs
424
+ nexus agent list --json | jq -r '.data[] | select(.status == "ACTIVE") | .id'
425
+
426
+ # Count deployments by type
427
+ nexus deployment list --json | jq '.data | group_by(.type) | map({type: .[0].type, count: length})'
428
+ ```
429
+
430
+ ### Bulk Operations
431
+
432
+ ```bash
433
+ # Update all agents to use a specific model
434
+ nexus agent list --json | jq -r '.data[].id' | while read id; do
435
+ nexus agent update "$id" --model gpt-4o
436
+ echo "Updated $id"
437
+ done
438
+ ```
439
+
440
+ ### Raw API Passthrough
441
+
442
+ For endpoints without a dedicated CLI command:
443
+
444
+ ```bash
445
+ # GET request
446
+ nexus api GET /models
447
+
448
+ # POST with inline body
449
+ nexus api POST /agents --body '{"firstName":"Test","lastName":"Bot","role":"QA"}'
450
+
451
+ # GET with query parameters
452
+ nexus api GET /agents --query page=1 --query limit=5
453
+
454
+ # POST with body from file
455
+ nexus api PATCH /agents/abc-123 --body payload.json
456
+
457
+ # POST with body from stdin
458
+ echo '{"text":"hello"}' | nexus api POST /emulator/dep-1/sessions/s-1/messages --body -
459
+ ```
460
+
461
+ ### Suppress Confirmation Prompts (CI/CD)
462
+
463
+ ```bash
464
+ # Skip delete confirmation
465
+ nexus agent delete abc-123 --yes
466
+
467
+ # Preview what would be deleted without executing
468
+ nexus agent delete abc-123 --dry-run
469
+ ```
470
+
471
+ ### Load Prompts from Files
472
+
473
+ ```bash
474
+ # Create an agent with a prompt from a markdown file
475
+ nexus agent create \
476
+ --first-name Support --last-name Bot --role "Customer Support" \
477
+ --prompt ./prompts/support-agent.md
478
+
479
+ # Update an agent's prompt from stdin
480
+ cat new-prompt.md | nexus agent update abc-123 --prompt -
481
+ ```
482
+
483
+ ### Workflow Build Pipeline
484
+
485
+ ```bash
486
+ # Create, build, validate, test, and publish in one pipeline
487
+ WF_ID=$(nexus workflow create --name "Lead Qualifier" --json | jq -r '.id')
488
+
489
+ nexus workflow node create $WF_ID --type agentInputTrigger --name "Start"
490
+ nexus workflow node create $WF_ID --type aiTask --name "Qualify" \
491
+ --body '{"data":{"taskId":"task-123"}}'
492
+
493
+ nexus workflow validate $WF_ID
494
+ nexus workflow test $WF_ID --input '{"message":"I want to buy 100 units"}'
495
+ nexus workflow publish $WF_ID
496
+ ```
497
+
498
+ ---
499
+
500
+ ## SDK Cross-Reference
501
+
502
+ Every CLI command maps to an SDK method. Use the SDK (`@agent-nexus/sdk`) when building applications; use the CLI for scripting and exploration.
503
+
504
+ | CLI Command | SDK Equivalent |
505
+ | --------------------------------------- | ----------------------------------------------------- |
506
+ | `nexus agent list` | `client.agents.list()` |
507
+ | `nexus agent get <id>` | `client.agents.get(id)` |
508
+ | `nexus agent create --first-name X ...` | `client.agents.create({ firstName: "X", ... })` |
509
+ | `nexus agent update <id> --role Y` | `client.agents.update(id, { role: "Y" })` |
510
+ | `nexus agent delete <id>` | `client.agents.delete(id)` |
511
+ | `nexus agent-tool list <agentId>` | `client.agents.tools.list(agentId)` |
512
+ | `nexus version list <agentId>` | `client.agents.versions.list(agentId)` |
513
+ | `nexus workflow list` | `client.workflows.list()` |
514
+ | `nexus workflow publish <id>` | `client.workflows.publish(id)` |
515
+ | `nexus document upload <file>` | `client.documents.uploadFile(file)` |
516
+ | `nexus collection create --name X` | `client.documents.createCollection({ name: "X" })` |
517
+ | `nexus deployment create --name X ...` | `client.deployments.create({ name: "X", ... })` |
518
+ | `nexus emulator session create <depId>` | `client.emulator.createSession(depId)` |
519
+ | `nexus emulator send <depId> <sessId>` | `client.emulator.sendMessage(depId, sessId, { ... })` |
520
+ | `nexus tool search --query X` | `client.tools.search({ query: "X" })` |
521
+ | `nexus analytics overview` | `client.analytics.getOverview()` |
522
+ | `nexus model list` | `client.models.list()` |
523
+ | `nexus ticket create --title X ...` | `client.tickets.create({ title: "X", ... })` |
524
+ | `nexus phone-number list` | `client.phoneNumbers.list()` |
525
+
526
+ > **Full SDK documentation:** See [@agent-nexus/sdk README](../sdk/README.md)
527
+
528
+ ---
529
+
530
+ ## Error Handling
531
+
532
+ The CLI catches all errors and prints actionable messages with hints.
533
+
534
+ ### Error Types
535
+
536
+ | Error | Cause | Hint |
537
+ | -------------------------- | ------------------------------------ | ------------------------------------------------------ |
538
+ | **Authentication failed** | Invalid, missing, or expired API key | Run `nexus auth login` or set `NEXUS_API_KEY` |
539
+ | **Not found (404)** | Resource ID doesn't exist | Run `nexus <resource> list` to find valid IDs |
540
+ | **Validation error (422)** | Invalid request body or parameters | Add `--json` to see the `details` field |
541
+ | **Connection error** | Network issue or wrong base URL | Check `--base-url` and network connectivity |
542
+ | **API error (5xx)** | Server-side error | Retry after a moment; report via `nexus ticket create` |
543
+
544
+ ### Exit Codes
545
+
546
+ | Code | Meaning |
547
+ | ---- | ------------------------------------------------------------- |
548
+ | `0` | Success |
549
+ | `1` | Any error (authentication, API, validation, connection, etc.) |
550
+
551
+ ### Error Format
552
+
553
+ **Human-readable (default):**
554
+
555
+ ```
556
+ Error: Authentication failed — invalid or missing API key.
557
+ Run "nexus auth login" to re-authenticate, or set NEXUS_API_KEY.
558
+ ```
559
+
560
+ **JSON (`--json`):**
561
+
562
+ ```json
563
+ {
564
+ "error": {
565
+ "message": "Authentication failed — invalid or missing API key.",
566
+ "hint": "Run \"nexus auth login\" to re-authenticate, or set NEXUS_API_KEY."
567
+ }
568
+ }
569
+ ```
570
+
571
+ ---
572
+
573
+ ## Troubleshooting
574
+
575
+ ### "No API key found"
576
+
577
+ ```
578
+ Error: No API key found. Set NEXUS_API_KEY or run:
579
+ nexus auth login
580
+ ```
581
+
582
+ **Fix:** Run `nexus auth login` or set the `NEXUS_API_KEY` environment variable.
583
+
584
+ ### "Invalid key format -- keys start with nxs\_"
585
+
586
+ **Fix:** Copy the full API key from Settings > API Keys, including the `nxs_` prefix.
587
+
588
+ ### "Could not reach the Nexus API"
589
+
590
+ **Fix:** Check your network connection. If using a custom base URL, verify it:
591
+
592
+ ```bash
593
+ nexus auth whoami # shows the current base URL
594
+ ```
595
+
596
+ ### "Validation failed (HTTP 401)"
597
+
598
+ **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.
599
+
600
+ ### Colors Not Showing
601
+
602
+ The CLI disables colors when:
603
+
604
+ - `NO_COLOR` environment variable is set
605
+ - `--no-color` flag is passed
606
+ - stdout is not a TTY (e.g., piped to a file or another command)
607
+
608
+ ### Update Check Not Working
609
+
610
+ The version check cache is stored at `~/.nexus-mcp/version-check.json`. Delete it to force a fresh check:
611
+
612
+ ```bash
613
+ rm ~/.nexus-mcp/version-check.json
614
+ nexus agent list # triggers a new check
615
+ ```
616
+
617
+ ### Upgrade Failed
618
+
619
+ If `nexus upgrade` fails (e.g., permission denied), run the install manually:
620
+
621
+ ```bash
622
+ sudo npm install -g @agent-nexus/cli@latest
623
+ ```
624
+
625
+ ---
626
+
627
+ ## Configuration Files
628
+
629
+ | File | Purpose | Permissions |
630
+ | --------------------------------- | ---------------------------------------------------- | ----------- |
631
+ | `~/.nexus-mcp/config.json` | API key and base URL (written by `nexus auth login`) | `0600` |
632
+ | `~/.nexus-mcp/version-check.json` | Update check cache (auto-managed, checked once/day) | `0600` |
633
+
634
+ 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.
635
+
636
+ ### Config File Format
637
+
638
+ ```json
639
+ {
640
+ "apiKey": "nxs_your_api_key_here",
641
+ "baseUrl": "https://api.nexusgpt.io"
642
+ }
643
+ ```
644
+
645
+ ---
646
+
647
+ ## Related Resources
648
+
649
+ | Resource | Link |
650
+ | --------------------- | ------------------------------------------------------------------------------ |
651
+ | SDK | [`@agent-nexus/sdk`](../sdk/README.md) |
652
+ | Product Documentation | [`packages/docs`](../docs/) |
653
+ | Claude Code Skills | [`packages/claude-code-skills`](../claude-code-skills/) |
654
+ | API Reference | `https://api.nexusgpt.io/api/public/v1` |
655
+ | Dashboard | [app.nexusgpt.io](https://app.nexusgpt.io) |
656
+ | CLI Command Reference | [docs/command-reference.md](docs/command-reference.md) |
657
+ | Input/Output Guide | [docs/input-output-patterns.md](docs/input-output-patterns.md) |
658
+ | Common Gotchas | [docs/gotchas.md](docs/gotchas.md) |
659
+ | Recipes | [docs/recipes.md](docs/recipes.md) |
660
+ | Report Issues | `nexus ticket create --type BUG --title "..." --description "..."` |
661
+ | Request Features | `nexus ticket create --type FEATURE_REQUEST --title "..." --description "..."` |
662
+
663
+ ---
664
+
665
+ ## License
666
+
667
+ [MIT](LICENSE)