Sign in

Search issue titles and bodies, change requests and comments. Private repositories you cannot read are not included.
vole
Clone

Read only, no credentials:

https://rodent.software/vole.git

Write over SSH with a registered key:

git clone ssh://git@rodent.software:2222/vole.git

A free and open-source forge that lives in your Git repo.

Blame · docs/cli.md

Line attribution on main · 349 line(s)

View file History
520470e1
Keenan Nemetz
16d ago
 1 # CLI reference
2
3 The command line is Vole's admin interface. That is deliberate: if you can run
4 Vole on the machine, you are the operator. There is no separate admin panel to
5 secure or keep in sync.
6
7 Run `vole help` for the built-in summary. If you make a usage mistake, Vole exits
8 with code `129`, just like Git.
9
10 ## Common options
11
12 | Option | Used by | Meaning |
13 |---|---|---|
c36d5073
Keenan Nemetz
16d ago
 14 | `--config <path>` | Local server management | Use a different `vole.toml` (default: `./vole.toml`, then `~/.vole/vole.toml`; `VOLE_CONFIG` overrides both) |
ade6107e
Keenan Nemetz
16d ago
 15 | `--remote <name\|url>` | `admin`, issue, change, release, and pages commands | Git remote or instance SSH URL to talk to |
3abbe749
Keenan Nemetz
16d ago
 16 | `--json` | `admin --remote` | Print the server's JSON response |
ade6107e
Keenan Nemetz
16d ago
 17 | `--no-push` | `issue`, `change` | Commit locally without pushing |
520470e1
Keenan Nemetz
16d ago
 18 | `--dir <path>` | `init`, `workflow`, `runner` | Working or checkout directory |
19 | `--branch <name>` | `pages` | Site branch (default `pages`) |
e05f1c48
Keenan Nemetz
13d ago
 20 | `--format <fmt>` | `issue list`, `change list` | Output fields such as `%(id)`, `%(number)` and `%(title)`, or `json` |
520470e1
Keenan Nemetz
16d ago
 21 | `-h`, `--help` | All | Print usage |
22
23 Options follow Git's conventions: `--long value`, `--long=value`, `-o value`,
ade6107e
Keenan Nemetz
16d ago
 24 `-ovalue`, bundled short options such as `-am`, repeated options, and `--` to
25 end option parsing. Options may appear before or after arguments. `vole help
26 <command>` and `vole <command> -h` print that command's usage.
520470e1
Keenan Nemetz
16d ago
 27
0c40a1d3
Keenan Nemetz
7d ago
 28 ## Secrets
29
30 A repository's secrets are the values its maintainers share, stored on the
31 instance, encrypted, and never in the repository:
32
33 ```sh
34 vole secret list <repo>
35 vole secret set <repo> <NAME> # the value is read from stdin
36 vole secret set <repo> <NAME> --from-file key.pem
37 vole secret get <repo> <NAME> # the value, and nothing else
38 vole secret rm <repo> <NAME>
39 ```
40
41 `set` reads the value from standard input or a file and never from the command
42 line: an argument is visible to every process on the host and lands in shell
43 history. On a terminal it prompts without echoing; from a pipe it removes one
44 trailing newline, so `echo "$TOKEN" | vole secret set demo DEPLOY_KEY` stores the
45 token and not the line ending. `get` writes the value with no newline added, so it
46 can be redirected to a file.
47
48 `set` needs the maintainer role in that repository, and every read and change is
49 recorded in `data/audit.log`. `list` shows names, versions, who last changed one,
50 and when a value was last read — never a value. The same values appear on the
51 repository's **Settings** tab, which is write-only: a saved value is not shown
52 again.
53
54 Names are upper-case letters, digits and `_`, so a name can be read as an
55 environment variable. A value is limited to 128 KiB, the most one environment
56 variable can carry.
57
520470e1
Keenan Nemetz
16d ago
 58 ## Instance
59
60 ```sh
3b39a84c
Keenan Nemetz
14d ago
 61 vole admin init [--dir <path> | --config <path>]
520470e1
Keenan Nemetz
16d ago
 62 vole serve [--config <path>] [--log debug]
63 vole version
64 ```
65
3abbe749
Keenan Nemetz
16d ago
 66 ## Server management
67
2e024cc9
Keenan Nemetz
14d ago
 68 `vole admin` is the single namespace for account, repository (`repo`), and access
69 (`acl`) management.
3abbe749
Keenan Nemetz
16d ago
 70 Without `--remote`, it changes the instance named by the local `vole.toml`. With
71 `--remote`, it sends the same command over SSH and must be run by an instance
72 admin.
73
74 ```sh
2e024cc9
Keenan Nemetz
14d ago
 75 vole admin account create alice --key ~/.ssh/id_ed25519.pub
0f8054ad
Keenan Nemetz
13d ago
 76 vole admin --config /srv/vole/vole.toml account list
2e024cc9
Keenan Nemetz
14d ago
 77 vole admin --remote origin account create bob --key bob.pub
78 vole admin --remote ssh://git@forge.example.com:2222 account list
3abbe749
Keenan Nemetz
16d ago
 79 ```
80
0f8054ad
Keenan Nemetz
13d ago
 81 `--config` names a `vole.toml` other than the one discovery finds, and may sit on
82 either side of the command (`vole admin --config P account list` and `vole admin
83 account list --config P` are the same). It is local only: with `--remote` the
84 server's own config is the one that applies.
85
ab326d3a
Keenan Nemetz
14d ago
 86 See [Accounts and access](accounts-and-access.md#remote-administration).
3abbe749
Keenan Nemetz
16d ago
 87
2e024cc9
Keenan Nemetz
14d ago
 88 `vole admin account` is the documented spelling. The old `vole admin user` form
89 and the pre-admin aliases (`vole account`, `vole user`, `vole repo`, `vole acl`,
90 `vole index`, and `vole gc`) remain for compatibility; documentation and help use
91 `vole admin account`.
ade6107e
Keenan Nemetz
16d ago
 92
ab326d3a
Keenan Nemetz
14d ago
 93 ### Accounts
94
2e024cc9
Keenan Nemetz
14d ago
 95 The `account` commands manage accounts.
520470e1
Keenan Nemetz
16d ago
 96
97 ```sh
29a795b9
Keenan Nemetz
6d ago
 98 vole admin account create [--key <file|->] [--role <role>] [--bot] <name>
2e024cc9
Keenan Nemetz
14d ago
 99 vole admin account invite <name>
100 vole admin account credentials <name>
101 vole admin account rm-credential <name> <credential-id>
102 vole admin account sessions <name>
103 vole admin account revoke-sessions [--all | <name>]
104 vole admin account add-key --key <file|-> <name>
105 vole admin account rm-key <name> <fingerprint>
106 vole admin account retire <name>
107 vole admin account role <name> <none|read|contribute|maintain|admin>
108 vole admin account grant-admin <name>
109 vole admin account revoke-admin <name>
110 vole admin account show <name>
111 vole admin account list
112 vole admin account backup <path>
eec0e603
Keenan Nemetz
6d ago
 113 vole whoami [--remote <name>] [--role]
520470e1
Keenan Nemetz
16d ago
 114 ```
115
6c84d387
Keenan Nemetz
16d ago
 116 Omitting `--key` creates a browser-only account and prints a one-time enrollment
338a19dd
Keenan Nemetz
6d ago
 117 link. `--bot` creates an automation account instead: it has no browser sign-in and
118 cannot be an instance admin, so it must be created with a key. `--role` sets the
119 account's instance-wide role; it applies to public repositories, while `admin`
120 applies to every repository. `account role` changes it later. `account invite`
121 issues a fresh link for an existing account. `account backup` writes a file on the
122 host, so it is local-only.
520470e1
Keenan Nemetz
16d ago
 123
62576fa8
Keenan Nemetz
14d ago
 124 The account name is the only identifier an account has. It cannot be changed: it
a781cd9b
Keenan Nemetz
6d ago
 125 is the folder a `contribute` account's branches live under, so it is fixed at
126 creation and never reissued.
474a812d
Keenan Nemetz
16d ago
 127
eec0e603
Keenan Nemetz
6d ago
 128 `vole whoami` prints the account name. With `--role` it prints the effective role
129 on the repository named by the remote: the repository's default and per-account
130 rules, with the account's instance-wide role applied where the repository is
131 public. A private repository the account cannot read is reported as not found,
132 the same as a fetch.
133
3abbe749
Keenan Nemetz
16d ago
 134 ### Repositories
520470e1
Keenan Nemetz
16d ago
 135
136 ```sh
ab326d3a
Keenan Nemetz
14d ago
 137 vole admin repo create --owner <account> <name> [--description <text>]
3abbe749
Keenan Nemetz
16d ago
 138 vole admin repo list
139 vole admin repo show <name>
140 vole admin repo rename <old> <new>
141 vole admin repo delete <name>
520470e1
Keenan Nemetz
16d ago
 142 ```
143
144 New repositories are private. The owner becomes the first admin.
145
3abbe749
Keenan Nemetz
16d ago
 146 ### Access
520470e1
Keenan Nemetz
16d ago
 147
5b814e99
Keenan Nemetz
14d ago
 148 Instance-wide roles are account standing; repository rules are set with `acl`:
149
520470e1
Keenan Nemetz
16d ago
 150 ```sh
2e024cc9
Keenan Nemetz
14d ago
 151 vole admin account role <name> <none|read|contribute|maintain|admin>
152
3abbe749
Keenan Nemetz
16d ago
 153 vole admin acl show <repo>
2e024cc9
Keenan Nemetz
14d ago
 154 vole admin acl set-role <repo> <account> <none|read|contribute|maintain|admin>
155 vole admin acl set-default-role <repo> <none|read|contribute|maintain|admin>
156 vole admin acl set-approvals <repo> <n>
157
158 vole admin acl checks enable <repo>
159 vole admin acl checks disable <repo>
160
0789f22e
Keenan Nemetz
9d ago
 161 vole admin acl require-issues enable <repo>
162 vole admin acl require-issues disable <repo>
163
2e024cc9
Keenan Nemetz
14d ago
 164 vole admin acl protect list <repo>
165 vole admin acl protect add <repo> <ref-pattern>...
166 vole admin acl protect remove <repo> <ref-pattern>...
167 vole admin acl protect set <repo> <ref-pattern>...
168 vole admin acl protect clear <repo>
169
170 vole admin acl runners list <repo>
171 vole admin acl runners add <repo> <account>...
172 vole admin acl runners remove <repo> <account>...
173 vole admin acl runners set <repo> <account>...
174 vole admin acl runners clear <repo>
520470e1
Keenan Nemetz
16d ago
 175 ```
176
2e024cc9
Keenan Nemetz
14d ago
 177 `set-role` and `set-default-role` accept `none` to remove access. `protect set`
178 and `runners set` replace the whole list; the `add` and `remove` forms change one
0789f22e
Keenan Nemetz
9d ago
 179 entry at a time. `require-issues enable` makes a linked issue mandatory when a
180 new change request is opened.
2e024cc9
Keenan Nemetz
14d ago
 181
93c7cae8
Keenan Nemetz
21h ago
 182 A protected ref pattern is either an exact ref (`refs/heads/main`) or a ref
183 prefix ending in one `*` (`refs/heads/release/*`), the two shapes the hook
184 understands. `protect add` and `protect set` refuse anything else, because a
185 pattern that can never match would leave the branch open while `acl show` listed
186 it as protected. A misspelled category is named in the refusal:
187
188 ```console
189 $ vole admin acl protect add demo refs/head/main
190 vole: protected pattern "refs/head/main" cannot match any ref: did you mean "refs/heads/main"?
191 ```
192
ab326d3a
Keenan Nemetz
14d ago
 193 See [Accounts and access](accounts-and-access.md) and
70b70264
Keenan Nemetz
15d ago
 194 [Runners](runner.md#who-can-run-jobs-and-report-results).
520470e1
Keenan Nemetz
16d ago
 195
3abbe749
Keenan Nemetz
16d ago
 196 ### Maintenance
197
198 ```sh
199 vole admin gc [--dry-run] [--grace <duration>]
200 vole admin index rebuild
201 ```
202
203 These are local-only. See [Operations](operations.md).
204
520470e1
Keenan Nemetz
16d ago
 205 ## Issues
206
207 ```sh
ab326d3a
Keenan Nemetz
14d ago
 208 vole issue new --title <title> [-m <text> | -F <file>] [-l <label>]... [-a <account>]...
f6f4b1db
Keenan Nemetz
15d ago
 209 vole issue comment <id> [-m <text> | -F <file>] [--reply-to <comment-id>]
520470e1
Keenan Nemetz
16d ago
 210 vole issue edit-comment <id> <comment-id> [-m <text> | -F <file>]
211 vole issue rm-comment <id> <comment-id>
ab326d3a
Keenan Nemetz
14d ago
 212 vole issue edit <id> [--title <title>] [-m <text> | -F <file>] [-l <label>]... [-a <account>]... [--unassign <account>]...
213 vole issue assign <id> <account>...
214 vole issue unassign <id> <account>...
520470e1
Keenan Nemetz
16d ago
 215 vole issue close <id>
216 vole issue reopen <id>
ab326d3a
Keenan Nemetz
14d ago
 217 vole issue list [--state open|closed|all] [-l <label>]... [--assignee <account>]... [--format <fmt>]
520470e1
Keenan Nemetz
16d ago
 218 vole issue show <id>
219 ```
220
221 Ids and comment ids accept a unique prefix. See [Issues](issues.md).
222
223 ## Change requests
224
225 ```sh
a0a7c73a
Keenan Nemetz
13d ago
 226 vole change new --title <title> --base <branch> [--head <rev>] [--closes <issue>]... [-m <text> | -F <file>]
ade6107e
Keenan Nemetz
16d ago
 227 vole change list [--state open|closed|all] [--format <fmt>]
04e00cfc
Keenan Nemetz
16d ago
 228 vole change show <id>
f6f4b1db
Keenan Nemetz
15d ago
 229 vole change comment <id> [-m <text> | -F <file>] [--path <file> --line <n> [--side new|old]] [--reply-to <comment-id>]
04e00cfc
Keenan Nemetz
16d ago
 230 vole change edit-comment <id> <comment-id> [-m <text> | -F <file>]
231 vole change rm-comment <id> <comment-id>
e050e14a
Keenan Nemetz
13d ago
 232 vole change update <id> [--base <branch>] [--head <rev>] [--closes <issue>]... [--no-closes]
ab326d3a
Keenan Nemetz
14d ago
 233 vole change approve <id> [--as <account>]
e5478085
Keenan Nemetz
11d ago
 234 vole change merge <id>
04e00cfc
Keenan Nemetz
16d ago
 235 vole change close <id>
236 vole change reopen <id>
520470e1
Keenan Nemetz
16d ago
 237 ```
238
04e00cfc
Keenan Nemetz
16d ago
 239 `change` also accepts `request`, `requests` and `cr` as compatibility aliases. An
a0a7c73a
Keenan Nemetz
13d ago
 240 approval is only accepted from the account it names. `--closes` takes a full
241 issue id (repeatable, comma lists accepted) and names the issues landing the
242 request closes; it replaces the list on `update`, and `--no-closes` clears it.
e050e14a
Keenan Nemetz
13d ago
 243 A request opened with `--head <branch>` follows that branch: a later push moves its
244 head and invalidates the old approvals and checks. `--head <commit>` (or a tag)
245 pins the request to that commit instead. `--base <branch>` on `update` retargets an
246 open request, which is how a stacked request moves onto `main` after the branch
247 below it lands; approvals named the old base and stop counting. See
248 [Change requests](change-requests.md).
520470e1
Keenan Nemetz
16d ago
 249
e5478085
Keenan Nemetz
11d ago
 250 `change merge` lands the request. When the combined result is still building it
251 prints that the request will merge when the result passes, which is the same
252 "merge when ready" a click on the page arms. `change show` prints the combined
253 result and whether the landing is ready.
254
520470e1
Keenan Nemetz
16d ago
 255 ## Releases
256
257 ```sh
258 vole release create <tag> (-m <text> | -F <file|->)
259 vole release attach <tag> <file>... [--remote <name>]
260 ```
261
262 `create` writes the annotated tag in the current repository; push it with
263 `git push --follow-tags`. See [Releases](releases.md).
264
265 ## Pages
266
267 ```sh
ade6107e
Keenan Nemetz
16d ago
 268 vole pages deploy [<dir>] [--branch <name>] [-m <text> | -F <file>] [--dry-run] [--remote <name>]
520470e1
Keenan Nemetz
16d ago
 269 vole pages status [--branch <name>] [--remote <name>]
270 vole pages unpublish [--branch <name>] [--remote <name>]
271 ```
272
273 See [Sites](sites.md).
274
275 ## CI
276
277 ```sh
18c559ea
Keenan Nemetz
3d ago
 278 vole runner --remote <ssh-url> [--once] [--jobs <n>] [--dir <path>] [--repos <name>]... [--label <name>]...
70b70264
Keenan Nemetz
15d ago
 279 [--container-runtime <name>] [--container-network none|bridge]
280 [--container-pull missing|always|never] [--container-user <uid:gid>] [--container-userns <mode>]
281 [--container-memory <size>] [--container-cpus <n>] [--container-pids <n>]
f594f1a1
Keenan Nemetz
5d ago
 282 [--cache-size <size>] [--git-cache-size <size>] [--no-cache]
92d8afc8
Keenan Nemetz
1h ago
 283 vole run list [--state <state>] [--branch <branch>] [--commit <sha>] [--limit <n>]
284 [--format <fmt>] [--remote <name|url>]
285 vole run show <id> [--remote <name|url>]
286 vole run logs <id> [--attempt <n>] [--step <n>] [--remote <name|url>]
deb024d4
Keenan Nemetz
6d ago
 287 vole run cancel <id> [--remote <name|url>]
70291860
Keenan Nemetz
6d ago
 288 vole run rerun <id> [--remote <name|url>]
520470e1
Keenan Nemetz
16d ago
 289 vole workflow check [--dir <path>]
290 vole workflow list [--dir <path>]
3abbe749
Keenan Nemetz
16d ago
 291 vole workflow run [--dir <path>] [<workflow>...] [--job <id>]...
3b39a84c
Keenan Nemetz
14d ago
 292 [--container-runtime <name>]
293 [--container-network none|bridge] [--container-pull missing|always|never]
294 [--container-user <uid:gid>] [--container-userns <mode>]
295 [--cache-size <size>] [--no-cache]
eb07ff56
Keenan Nemetz
8d ago
 296 vole workflow dispatch --remote <name|url> --workflow <path> [--ref <branch>]
297 [--input name=value]...
520470e1
Keenan Nemetz
16d ago
 298 ```
299
18c559ea
Keenan Nemetz
3d ago
 300 `--jobs` is how many jobs one runner process runs at once (default 1). Each is a
301 session of its own, so the container limits are per job and a machine running four
302 jobs needs room for four containers. Under `--once` the runner still starts `--jobs`
303 jobs, and exits when they all finish.
304
4ac42680
Keenan Nemetz
7d ago
 305 `workflow run` executes steps in the working tree, in the job's image. It needs no
306 runner, but it does read the secrets its jobs declare from the instance the
307 checkout's `origin` names, using your key; a value it cannot read is left unset with
e82bbe7d
Keenan Nemetz
7d ago
 308 a note, and the values it did read are masked in the output. It needs a container
309 runtime; there is no host mode. Both it and
f594f1a1
Keenan Nemetz
5d ago
 310 `vole runner` reuse a job cache (see [Runners § Caching](runner.md#caching)). A
311 runner also keeps a copy of every repository it builds and clones each job from it,
312 so the history crosses the network once rather than once per run (see
313 [Runners § Saved checkouts](runner.md#saved-checkouts)). See
70b70264
Keenan Nemetz
15d ago
 314 [Workflows § Check and run a workflow locally](workflows.md#check-and-run-a-workflow-locally).
520470e1
Keenan Nemetz
16d ago
 315
eb07ff56
Keenan Nemetz
8d ago
 316 `workflow dispatch` queues a manual run on the instance instead. The workflow must
317 declare `on.workflow-dispatch`; `--ref` defaults to the default branch, and each
318 `--input` is checked against the input's declared type, options, and default. Only
319 a maintainer or instance admin may dispatch.
320
92d8afc8
Keenan Nemetz
1h ago
 321 `run list`, `run show` and `run logs` are the CLI half of the runs page and a run's
322 log. The queue lives on the instance, so they read it over the key you push with; any
323 account that may read the repository may use them. `run list` defaults to the newest
324 20 runs and narrows by status, branch or a commit id or prefix. `--format` understands
325 `%(id)`, `%(shortid)`, `%(status)`, `%(workflow)`, `%(job)`, `%(branch)`, `%(sha)`,
326 `%(trigger)`, `%(trigger_title)`, `%(exit)`, `%(attempts)`, `%(log)` and `%(created)`.
327
328 `run show` prints the run's status, commit, trigger, steps with their exit codes and
329 durations, each attempt's log size, the published artifacts, and whether the result
330 counts as a check. The id is the 26-character one on the run page; `vole change show`
331 also lists the head's runs, and the combined result's runs when there is one, so a
332 reviewer can copy the failing id without opening the browser.
333
334 `run logs` writes the bytes the runner wrote to stdout, with nothing added, so it can
335 be redirected or piped. It opens the attempt the run is on, or the newest logged
336 attempt once the run has finished; `--attempt` picks a retry and `--step` narrows the
337 output to one step's range inside it. A refusal goes to stderr, so a redirect produces
338 a log or an empty file.
339
340 `run cancel` is the CLI counterpart of the cancel button on a run page. A queued run
341 is canceled outright, and a running one is asked to stop, with its runner stopping at
342 the next heartbeat. `run rerun` queues a finished run again with the same pinned job.
343 Only a maintainer or instance admin may do either, and `data/audit.log` records the
344 account, the repository, and the run (`run.cancel` or `run.rerun`).
deb024d4
Keenan Nemetz
6d ago
 345
520470e1
Keenan Nemetz
16d ago
 346 ## Internal
347
348 `vole hook pre-receive|post-receive` is installed in repositories by Vole. It is
349 not intended to be run by hand.