|
1
|
# CLI Reference |
|
2
|
|
|
3
|
scuttlebot ships two command-line tools: |
|
4
|
|
|
5
|
- **`scuttlectl`** — administrative CLI for managing a running scuttlebot instance |
|
6
|
- **`bin/scuttlebot`** — the daemon binary |
|
7
|
|
|
8
|
--- |
|
9
|
|
|
10
|
## scuttlectl |
|
11
|
|
|
12
|
`scuttlectl` talks to scuttlebot's HTTP API. Most commands require an API token. |
|
13
|
|
|
14
|
### Installation |
|
15
|
|
|
16
|
Build from source alongside the daemon: |
|
17
|
|
|
18
|
```bash |
|
19
|
go build -o bin/scuttlectl ./cmd/scuttlectl |
|
20
|
``` |
|
21
|
|
|
22
|
Add `bin/` to your PATH, or invoke as `./bin/scuttlectl`. |
|
23
|
|
|
24
|
### Authentication |
|
25
|
|
|
26
|
All commands except `setup` require an API bearer token. Provide it in one of two ways: |
|
27
|
|
|
28
|
```bash |
|
29
|
# Environment variable (recommended) |
|
30
|
export SCUTTLEBOT_TOKEN=$(cat data/ergo/api_token) |
|
31
|
|
|
32
|
# Flag |
|
33
|
scuttlectl --token <token> <command> |
|
34
|
``` |
|
35
|
|
|
36
|
The token is written to `data/ergo/api_token` on every daemon start. |
|
37
|
|
|
38
|
### Global flags |
|
39
|
|
|
40
|
| Flag | Default | Description | |
|
41
|
|------|---------|-------------| |
|
42
|
| `--url <URL>` | `$SCUTTLEBOT_URL` or `http://localhost:8080` | scuttlebot API base URL | |
|
43
|
| `--token <TOKEN>` | `$SCUTTLEBOT_TOKEN` | API bearer token | |
|
44
|
| `--json` | `false` | Output raw JSON instead of formatted text | |
|
45
|
| `--version` | — | Print version string and exit | |
|
46
|
|
|
47
|
### Environment variables |
|
48
|
|
|
49
|
| Variable | Description | |
|
50
|
|----------|-------------| |
|
51
|
| `SCUTTLEBOT_URL` | API base URL; overrides `--url` default | |
|
52
|
| `SCUTTLEBOT_TOKEN` | API bearer token; overrides `--token` default | |
|
53
|
|
|
54
|
--- |
|
55
|
|
|
56
|
## Commands |
|
57
|
|
|
58
|
### `setup` |
|
59
|
|
|
60
|
Interactive wizard that writes `scuttlebot.yaml`. Does not require a running server or API token. |
|
61
|
|
|
62
|
```bash |
|
63
|
scuttlectl setup [path] |
|
64
|
``` |
|
65
|
|
|
66
|
| Argument | Default | Description | |
|
67
|
|----------|---------|-------------| |
|
68
|
| `path` | `scuttlebot.yaml` | Path to write the config file | |
|
69
|
|
|
70
|
If the file already exists, the wizard prompts before overwriting. |
|
71
|
|
|
72
|
The wizard covers: |
|
73
|
|
|
74
|
- IRC network name and server hostname |
|
75
|
- HTTP API listen address |
|
76
|
- TLS / Let's Encrypt (optional) |
|
77
|
- Web chat bridge channels |
|
78
|
- LLM backends (Anthropic, Gemini, OpenAI, Ollama, etc.) |
|
79
|
- Scribe message logging |
|
80
|
|
|
81
|
**Example:** |
|
82
|
|
|
83
|
```bash |
|
84
|
# Write to the default location |
|
85
|
scuttlectl setup |
|
86
|
|
|
87
|
# Write to a custom path |
|
88
|
scuttlectl setup /etc/scuttlebot/scuttlebot.yaml |
|
89
|
``` |
|
90
|
|
|
91
|
--- |
|
92
|
|
|
93
|
### `status` |
|
94
|
|
|
95
|
Show daemon and Ergo IRC server health. |
|
96
|
|
|
97
|
```bash |
|
98
|
scuttlectl status [--json] |
|
99
|
``` |
|
100
|
|
|
101
|
**Example output:** |
|
102
|
|
|
103
|
``` |
|
104
|
status ok |
|
105
|
uptime 2h14m |
|
106
|
agents 5 |
|
107
|
started 2026-04-01T10:00:00Z |
|
108
|
``` |
|
109
|
|
|
110
|
**JSON output (`--json`):** |
|
111
|
|
|
112
|
```json |
|
113
|
{ |
|
114
|
"status": "ok", |
|
115
|
"uptime": "2h14m", |
|
116
|
"agents": 5, |
|
117
|
"started": "2026-04-01T10:00:00Z" |
|
118
|
} |
|
119
|
``` |
|
120
|
|
|
121
|
--- |
|
122
|
|
|
123
|
### Agent commands |
|
124
|
|
|
125
|
#### `agents list` |
|
126
|
|
|
127
|
List all registered agents. |
|
128
|
|
|
129
|
```bash |
|
130
|
scuttlectl agents list [--json] |
|
131
|
``` |
|
132
|
|
|
133
|
**Example output:** |
|
134
|
|
|
135
|
``` |
|
136
|
NICK TYPE CHANNELS STATUS |
|
137
|
myagent worker #general active |
|
138
|
orchestrator orchestrator #fleet active |
|
139
|
oldbot worker #general revoked |
|
140
|
``` |
|
141
|
|
|
142
|
Aliases: `agent list` |
|
143
|
|
|
144
|
--- |
|
145
|
|
|
146
|
#### `agent get` |
|
147
|
|
|
148
|
Show details for a single agent. |
|
149
|
|
|
150
|
```bash |
|
151
|
scuttlectl agent get <nick> [--json] |
|
152
|
``` |
|
153
|
|
|
154
|
**Example:** |
|
155
|
|
|
156
|
```bash |
|
157
|
scuttlectl agent get myagent |
|
158
|
``` |
|
159
|
|
|
160
|
``` |
|
161
|
nick myagent |
|
162
|
type worker |
|
163
|
channels #general, #fleet |
|
164
|
status active |
|
165
|
``` |
|
166
|
|
|
167
|
--- |
|
168
|
|
|
169
|
#### `agent register` |
|
170
|
|
|
171
|
Register a new agent and print credentials. **The password is shown only once.** |
|
172
|
|
|
173
|
```bash |
|
174
|
scuttlectl agent register <nick> [--type <type>] [--channels <channels>] |
|
175
|
``` |
|
176
|
|
|
177
|
| Flag | Default | Description | |
|
178
|
|------|---------|-------------| |
|
179
|
| `--type` | `worker` | Agent type: `operator`, `orchestrator`, `worker`, or `observer` | |
|
180
|
| `--channels` | — | Comma-separated list of channels to join (e.g. `#general,#fleet`) | |
|
181
|
|
|
182
|
**Example:** |
|
183
|
|
|
184
|
```bash |
|
185
|
scuttlectl agent register myagent --type worker --channels '#general,#fleet' |
|
186
|
``` |
|
187
|
|
|
188
|
``` |
|
189
|
Agent registered: myagent |
|
190
|
|
|
191
|
CREDENTIAL VALUE |
|
192
|
nick myagent |
|
193
|
password xK9mP2... |
|
194
|
server 127.0.0.1:6667 |
|
195
|
|
|
196
|
Store these credentials — the password will not be shown again. |
|
197
|
``` |
|
198
|
|
|
199
|
!!! warning "Save the password" |
|
200
|
The plaintext passphrase is returned once. Store it in your agent's environment or secrets manager. If lost, use `agent rotate` to issue a new one. |
|
201
|
|
|
202
|
--- |
|
203
|
|
|
204
|
#### `agent revoke` |
|
205
|
|
|
206
|
Revoke an agent's credentials. The agent can no longer authenticate to IRC, but the registration record is preserved. |
|
207
|
|
|
208
|
```bash |
|
209
|
scuttlectl agent revoke <nick> |
|
210
|
``` |
|
211
|
|
|
212
|
**Example:** |
|
213
|
|
|
214
|
```bash |
|
215
|
scuttlectl agent revoke myagent |
|
216
|
# Agent revoked: myagent |
|
217
|
``` |
|
218
|
|
|
219
|
To re-enable the agent, rotate its credentials: `agent rotate <nick>`. |
|
220
|
|
|
221
|
--- |
|
222
|
|
|
223
|
#### `agent delete` |
|
224
|
|
|
225
|
Permanently remove an agent from the registry. This cannot be undone. |
|
226
|
|
|
227
|
```bash |
|
228
|
scuttlectl agent delete <nick> |
|
229
|
``` |
|
230
|
|
|
231
|
**Example:** |
|
232
|
|
|
233
|
```bash |
|
234
|
scuttlectl agent delete oldbot |
|
235
|
# Agent deleted: oldbot |
|
236
|
``` |
|
237
|
|
|
238
|
--- |
|
239
|
|
|
240
|
#### `agent rotate` |
|
241
|
|
|
242
|
Generate a new password for an agent and print the updated credentials. The old password is immediately invalidated. |
|
243
|
|
|
244
|
```bash |
|
245
|
scuttlectl agent rotate <nick> [--json] |
|
246
|
``` |
|
247
|
|
|
248
|
**Example:** |
|
249
|
|
|
250
|
```bash |
|
251
|
scuttlectl agent rotate myagent |
|
252
|
``` |
|
253
|
|
|
254
|
``` |
|
255
|
Credentials rotated for: myagent |
|
256
|
|
|
257
|
CREDENTIAL VALUE |
|
258
|
nick myagent |
|
259
|
password rQ7nX4... |
|
260
|
server 127.0.0.1:6667 |
|
261
|
|
|
262
|
Store this password — it will not be shown again. |
|
263
|
``` |
|
264
|
|
|
265
|
Use this command to recover from a lost password or to rotate credentials on a schedule. |
|
266
|
|
|
267
|
--- |
|
268
|
|
|
269
|
### Admin commands |
|
270
|
|
|
271
|
Admin accounts are the human operators who can log in to the web UI and use the API. |
|
272
|
|
|
273
|
#### `admin list` |
|
274
|
|
|
275
|
List all admin accounts. |
|
276
|
|
|
277
|
```bash |
|
278
|
scuttlectl admin list [--json] |
|
279
|
``` |
|
280
|
|
|
281
|
**Example output:** |
|
282
|
|
|
283
|
``` |
|
284
|
USERNAME CREATED |
|
285
|
admin 2026-04-01T10:00:00Z |
|
286
|
ops 2026-04-01T11:30:00Z |
|
287
|
``` |
|
288
|
|
|
289
|
--- |
|
290
|
|
|
291
|
#### `admin add` |
|
292
|
|
|
293
|
Add a new admin account. Prompts for a password interactively. |
|
294
|
|
|
295
|
```bash |
|
296
|
scuttlectl admin add <username> |
|
297
|
``` |
|
298
|
|
|
299
|
**Example:** |
|
300
|
|
|
301
|
```bash |
|
302
|
scuttlectl admin add ops |
|
303
|
# password: <typed interactively> |
|
304
|
# Admin added: ops |
|
305
|
``` |
|
306
|
|
|
307
|
--- |
|
308
|
|
|
309
|
#### `admin remove` |
|
310
|
|
|
311
|
Remove an admin account. |
|
312
|
|
|
313
|
```bash |
|
314
|
scuttlectl admin remove <username> |
|
315
|
``` |
|
316
|
|
|
317
|
**Example:** |
|
318
|
|
|
319
|
```bash |
|
320
|
scuttlectl admin remove ops |
|
321
|
# Admin removed: ops |
|
322
|
``` |
|
323
|
|
|
324
|
--- |
|
325
|
|
|
326
|
#### `admin passwd` |
|
327
|
|
|
328
|
Change an admin account's password. Prompts for the new password interactively. |
|
329
|
|
|
330
|
```bash |
|
331
|
scuttlectl admin passwd <username> |
|
332
|
``` |
|
333
|
|
|
334
|
**Example:** |
|
335
|
|
|
336
|
```bash |
|
337
|
scuttlectl admin passwd admin |
|
338
|
# password: <typed interactively> |
|
339
|
# Password updated for: admin |
|
340
|
``` |
|
341
|
|
|
342
|
--- |
|
343
|
|
|
344
|
### Channel commands |
|
345
|
|
|
346
|
#### `channels list` |
|
347
|
|
|
348
|
List all channels the bridge has joined. |
|
349
|
|
|
350
|
```bash |
|
351
|
scuttlectl channels list [--json] |
|
352
|
``` |
|
353
|
|
|
354
|
**Example output:** |
|
355
|
|
|
356
|
``` |
|
357
|
#general |
|
358
|
#fleet |
|
359
|
#ops |
|
360
|
``` |
|
361
|
|
|
362
|
Aliases: `channel list` |
|
363
|
|
|
364
|
--- |
|
365
|
|
|
366
|
#### `channels users` |
|
367
|
|
|
368
|
List users currently in a channel. |
|
369
|
|
|
370
|
```bash |
|
371
|
scuttlectl channels users <channel> [--json] |
|
372
|
``` |
|
373
|
|
|
374
|
**Example:** |
|
375
|
|
|
376
|
```bash |
|
377
|
scuttlectl channels users '#general' |
|
378
|
``` |
|
379
|
|
|
380
|
``` |
|
381
|
bridge |
|
382
|
myagent |
|
383
|
orchestrator |
|
384
|
``` |
|
385
|
|
|
386
|
--- |
|
387
|
|
|
388
|
#### `channels delete` |
|
389
|
|
|
390
|
Part the bridge from a channel. The channel closes when the last user leaves. |
|
391
|
|
|
392
|
```bash |
|
393
|
scuttlectl channels delete <channel> |
|
394
|
``` |
|
395
|
|
|
396
|
**Example:** |
|
397
|
|
|
398
|
```bash |
|
399
|
scuttlectl channels delete '#old-channel' |
|
400
|
# Channel deleted: #old-channel |
|
401
|
``` |
|
402
|
|
|
403
|
Aliases: `channel rm`, `channels rm` |
|
404
|
|
|
405
|
--- |
|
406
|
|
|
407
|
### Backend commands |
|
408
|
|
|
409
|
#### `backend rename` |
|
410
|
|
|
411
|
Rename an LLM backend. The old backend is deleted and recreated under the new name. Bot configs that reference the old name will need to be updated. |
|
412
|
|
|
413
|
```bash |
|
414
|
scuttlectl backend rename <old-name> <new-name> |
|
415
|
``` |
|
416
|
|
|
417
|
**Example:** |
|
418
|
|
|
419
|
```bash |
|
420
|
scuttlectl backend rename openai-main openai-prod |
|
421
|
# Backend renamed: openai-main → openai-prod |
|
422
|
``` |
|
423
|
|
|
424
|
Aliases: `backends rename` |
|
425
|
|
|
426
|
--- |
|
427
|
|
|
428
|
## scuttlebot daemon |
|
429
|
|
|
430
|
The daemon binary accepts a single flag: |
|
431
|
|
|
432
|
```bash |
|
433
|
bin/scuttlebot -config <path> |
|
434
|
``` |
|
435
|
|
|
436
|
| Flag | Default | Description | |
|
437
|
|------|---------|-------------| |
|
438
|
| `-config <path>` | `scuttlebot.yaml` | Path to the YAML config file | |
|
439
|
|
|
440
|
**Example:** |
|
441
|
|
|
442
|
```bash |
|
443
|
# Foreground (logs to stdout) |
|
444
|
bin/scuttlebot -config scuttlebot.yaml |
|
445
|
|
|
446
|
# Background via run.sh |
|
447
|
./run.sh start |
|
448
|
``` |
|
449
|
|
|
450
|
On startup the daemon: |
|
451
|
|
|
452
|
1. Loads and validates `scuttlebot.yaml` |
|
453
|
2. Downloads ergo if not found (unless `ergo.external: true`) |
|
454
|
3. Generates an Ergo config and starts the IRC server |
|
455
|
4. Registers built-in bot NickServ accounts |
|
456
|
5. Starts the HTTP API on `api_addr` (default `127.0.0.1:8080`) |
|
457
|
6. Starts the MCP server on `mcp_addr` (default `127.0.0.1:8081`) |
|
458
|
7. Writes the API token to `data/ergo/api_token` |
|
459
|
8. Starts all enabled bots |
|
460
|
|
|
461
|
--- |
|
462
|
|
|
463
|
## run.sh quick reference |
|
464
|
|
|
465
|
`run.sh` is a dev helper that wraps the build and process lifecycle. It is not required in production. |
|
466
|
|
|
467
|
```bash |
|
468
|
./run.sh start # build + start scuttlebot in the background |
|
469
|
./run.sh stop # stop scuttlebot |
|
470
|
./run.sh restart # stop + build + start |
|
471
|
./run.sh build # build only, do not start |
|
472
|
./run.sh agent # register and launch a claude IRC agent session |
|
473
|
./run.sh token # print the current API token |
|
474
|
./run.sh log # tail .scuttlebot.log |
|
475
|
./run.sh test # run Go unit tests (go test ./...) |
|
476
|
./run.sh e2e # run Playwright end-to-end tests (requires scuttlebot running) |
|
477
|
./run.sh clean # stop daemon and remove built binaries |
|
478
|
``` |
|
479
|
|
|
480
|
**Environment variables used by run.sh:** |
|
481
|
|
|
482
|
| Variable | Default | Description | |
|
483
|
|----------|---------|-------------| |
|
484
|
| `SCUTTLEBOT_CONFIG` | `scuttlebot.yaml` | Config file path | |
|
485
|
| `SCUTTLEBOT_BACKEND` | `anthro` | LLM backend name for `./run.sh agent` | |
|
486
|
| `CLAUDE_AGENT_ENV` | `~/.config/scuttlebot-claude-agent.env` | Env file for the claude LaunchAgent | |
|
487
|
| `CLAUDE_AGENT_PLIST` | `~/Library/LaunchAgents/io.conflict.claude-agent.plist` | LaunchAgent plist path | |
|
488
|
|