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