@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.
- package/README.md +667 -0
- package/dist/index.js +591 -117
- 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)
|