1# CLI
2
3The `ermite` binary also drives a running server over its API. Run `ermite <command> --help` for the details of each command.
4
5## Connect to a server
6
7| Setting | Environment | Config file key |
8|---|---|---|
9| server address | `ERMITE_URL` | `url` |
10| token (optional for public reads) | `ERMITE_TOKEN` | `token.cmd`, a command that prints it |
11
12The environment wins over the config file.
13
14```sh
15ermite config set url https://git.example.com
16ermite config set token.cmd 'pass show ermite/token'
17ermite config show [--json]   # path and values
18ermite config unset <key>
19```
20
21The file holds no secret, only the command that fetches the token (`pass`, `gopass show -o`, `op read`, `secret-tool lookup`, …):
22
23```ini
24# ~/.config/ermite/config
25url       = https://git.example.com
26token.cmd = pass show ermite/token
27```
28
29Location: `$XDG_CONFIG_HOME/ermite/config`, `~/Library/Application Support/ermite/config` on macOS, `%AppData%\ermite\config` on Windows. `ERMITE_CONFIG` names another file.
30
31A token sent over plain `http://` to a non-loopback host prints a warning.
32
33### How `token.cmd` runs
34
35- Through `sh -c` (`cmd /C` on Windows), at most once per run, only when a command needs the token.
36- It gets your terminal when stdin is one, so pinentry or biometric prompts work.
37- It must print the token alone on one line, under 4 KiB, within 60 seconds. On timeout or interrupt it is killed.
38- A failure is reported in one line, without the command's output.
39
40It does not run:
41
42- when `ERMITE_TOKEN` is set;
43- for `ermite version`, `ermite config` or shell completion;
44- when `ERMITE_URL` points to another server than the file's `url` (the call is anonymous; set `ERMITE_TOKEN`);
45- when the file or its directory is writable by other users, or owned by another user (not checked on Windows).
46
47## Commands
48
49```sh
50ermite repo list | show <name> | create <name> [--description …] [--visibility public]
51ermite repo edit <name> [--description …] [--visibility …] [--default-branch …] [--merge-modes …] [--failing-checks-block=false]
52ermite repo delete <name> [--yes]
53
54ermite token create <label> [--preset cli|agent|ci|runner] [--scope …] [--repo …] [--branch-prefix …] [--expires 30d]
55ermite token list | revoke <id>
56
57ermite mr create <repo> --source <branch> --title … | list <repo> | show <repo> <n> [--diff]
58ermite mr comment <repo> <n> -m … [--path … --line … --side old|new] | resolve <repo> <n> <comment>
59ermite mr merge <repo> <n> --head <id> [--squash] [--delete-branch] | close <repo> <n>
60
61ermite run list <repo> [--workflow …] [--branch …] [--status …]
62ermite run view <repo> <id> [--attempt n] [--log [--job …]] [--summary]
63ermite run watch <repo> <id> [--log] | cancel <repo> <id> | rerun <repo> <id> [--failed]
64ermite run artifacts <repo> <id> | download <repo> <id> [--name N]… [--dir D]
65ermite workflow run <file> --repo <repo> [--ref …] [-f name=value …]
66ermite workflow list <repo> [--json]
67ermite workflow disable <repo> <file>    # no event starts a run of it; the file need not exist yet
68ermite workflow enable <repo> <file>
69ermite runner list | remove <id>
70ermite secret set|list|delete …         # CI secrets (needs ERMITE_SECRETS_KEY)
71ermite variable set|get|list|delete …
72ermite environment create|list|delete … --repo <repo>
73
74ermite web login                         # one-time sign-in link (60 s)
75ermite web logout --all                  # sign every browser out
76ermite web passkey list | remove <id>
77ermite signing-key show                  # public key of squash commits
78ermite oidc rotate-key
79ermite watch [repo] [--json]             # follow live events
80ermite version                           # client and server versions
81ermite completion bash|zsh|fish
82```
83
84## Output
85
86- `--json` prints stable field names (listed in each `--help`) on `repo list|show|create|edit`, `token create|list`, `run list|view|cancel|rerun`, `runner list` and `version`.
87- `watch --json` prints one object per line.
88- Errors are one line on stderr (`ermite: …`) with exit status 1.
89- Shell completion completes repository names from the server.