docs(cli): document the token.cmd kill, the Windows limit and config show --json
README and the agent skill describe how token.cmd is stopped on a timeout or a signal, that the permission check does not exist on Windows, and the --json flag of config show.
- commit
- ea2844737d006f32ce57faa14e1f0a7d8331dcc6
- author
- brice · · 2026-10-12 16:17 UTC
- parent
- 0587f1c
- signature
- GPG Verified
CD88F9E564E0102646FB6077A1A07C7C7C3E349D· arch-gpg Verified for the committer email
2 files · +4 -4
M README.md +3 -3
| @@ -52,10 +52,10 @@ token.cmd = pass show ermite/token | |||
| 52 | 52 | ```sh | |
| 53 | 53 | ermite config set url https://git.example.com | |
| 54 | 54 | ermite config set token.cmd 'pass show ermite/token' # or: gopass show -o ermite/token, op read op://vault/ermite/token, secret-tool lookup service ermite | |
| 55 | - | ermite config show # path and stored values; unset removes a key | |
| 55 | + | ermite config show [--json] # path and stored values; unset removes a key | |
| 56 | 56 | ``` | |
| 57 | 57 | ||
| 58 | - | `token.cmd` runs with `sh -c` (`cmd /C` on Windows) only when a command needs the token, at most once per run, with your environment and, when standard input is a terminal, that terminal (so a pinentry or biometric prompt works; otherwise it reads nothing). It must print the token alone on one line, in under 4 KiB, within 60 seconds. It is not run when `ERMITE_TOKEN` is set, nor by `ermite version` or `ermite config`, and not when the config file, or the directory holding it, can be written by other users or the file belongs to another user. It belongs to the server of the file: when `ERMITE_URL` names a different server than the file's `url`, it is not run and the call is anonymous (with a notice; set `ERMITE_TOKEN` to authenticate there). A failure is reported in one line without its output. Shell completion never runs it: it is anonymous unless `ERMITE_TOKEN` is set. | |
| 58 | + | `token.cmd` runs with `sh -c` (`cmd /C` on Windows) only when a command needs the token, at most once per run, with your environment and, when standard input is a terminal, that terminal (so a pinentry or biometric prompt works; otherwise it reads nothing). On a timeout or when ermite is interrupted or terminated, the command and everything it started are killed (when standard input is a terminal, only the shell is, so that prompts keep working). It must print the token alone on one line, in under 4 KiB, within 60 seconds. It is not run when `ERMITE_TOKEN` is set, nor by `ermite version` or `ermite config`, and not when the config file, or the directory holding it, can be written by other users or the file belongs to another user (`ermite config show` and `set` warn about it). On Windows this check does not exist: keep the file in your own profile, the default place. It belongs to the server of the file: when `ERMITE_URL` names a different server than the file's `url`, it is not run and the call is anonymous (with a notice; set `ERMITE_TOKEN` to authenticate there). A failure is reported in one line without its output. Shell completion never runs it: it is anonymous unless `ERMITE_TOKEN` is set. | |
| 59 | 59 | ||
| 60 | 60 | ```sh | |
| 61 | 61 | export ERMITE_URL=https://git.example.com ERMITE_TOKEN=ermite_... | |
| @@ -68,7 +68,7 @@ ermite mr merge <repo> <n> --head <id> [--squash] [--delete-branch] | close <rep | |||
| 68 | 68 | ermite web login # prints a one-time sign-in link (60 s) | |
| 69 | 69 | ermite web logout --all # signs every browser out | |
| 70 | 70 | ermite signing-key show # public key and allowed_signers line of squash commits | |
| 71 | - | ermite config show | set <url|token.cmd> <value> | unset <key> # the CLI config file | |
| 71 | + | ermite config show [--json] | set <url|token.cmd> <value> | unset <key> # the CLI config file | |
| 72 | 72 | ermite version # client and server, warns about missing server features | |
| 73 | 73 | ermite watch [repo] [--json] # follows events, reconnects and resumes | |
| 74 | 74 | ``` | |
| @@ -52,10 +52,10 @@ token.cmd = pass show ermite/token | |||||
| 52 | ```sh | 52 | ```sh | ||
| 53 | ermite config set url https://git.example.com | 53 | ermite config set url https://git.example.com | ||
| 54 | ermite config set token.cmd 'pass show ermite/token' # or: gopass show -o ermite/token, op read op://vault/ermite/token, secret-tool lookup service ermite | 54 | ermite config set token.cmd 'pass show ermite/token' # or: gopass show -o ermite/token, op read op://vault/ermite/token, secret-tool lookup service ermite | ||
| 55 | - | ermite config show # path and stored values; unset removes a key | 55 | + | ermite config show [--json] # path and stored values; unset removes a key |
| 56 | ``` | 56 | ``` | ||
| 57 | 57 | ||||
| 58 | - | `token.cmd` runs with `sh -c` (`cmd /C` on Windows) only when a command needs the token, at most once per run, with your environment and, when standard input is a terminal, that terminal (so a pinentry or biometric prompt works; otherwise it reads nothing). It must print the token alone on one line, in under 4 KiB, within 60 seconds. It is not run when `ERMITE_TOKEN` is set, nor by `ermite version` or `ermite config`, and not when the config file, or the directory holding it, can be written by other users or the file belongs to another user. It belongs to the server of the file: when `ERMITE_URL` names a different server than the file's `url`, it is not run and the call is anonymous (with a notice; set `ERMITE_TOKEN` to authenticate there). A failure is reported in one line without its output. Shell completion never runs it: it is anonymous unless `ERMITE_TOKEN` is set. | 58 | + | `token.cmd` runs with `sh -c` (`cmd /C` on Windows) only when a command needs the token, at most once per run, with your environment and, when standard input is a terminal, that terminal (so a pinentry or biometric prompt works; otherwise it reads nothing). On a timeout or when ermite is interrupted or terminated, the command and everything it started are killed (when standard input is a terminal, only the shell is, so that prompts keep working). It must print the token alone on one line, in under 4 KiB, within 60 seconds. It is not run when `ERMITE_TOKEN` is set, nor by `ermite version` or `ermite config`, and not when the config file, or the directory holding it, can be written by other users or the file belongs to another user (`ermite config show` and `set` warn about it). On Windows this check does not exist: keep the file in your own profile, the default place. It belongs to the server of the file: when `ERMITE_URL` names a different server than the file's `url`, it is not run and the call is anonymous (with a notice; set `ERMITE_TOKEN` to authenticate there). A failure is reported in one line without its output. Shell completion never runs it: it is anonymous unless `ERMITE_TOKEN` is set. |
| 59 | 59 | ||||
| 60 | ```sh | 60 | ```sh | ||
| 61 | export ERMITE_URL=https://git.example.com ERMITE_TOKEN=ermite_... | 61 | export ERMITE_URL=https://git.example.com ERMITE_TOKEN=ermite_... | ||
| @@ -68,7 +68,7 @@ ermite mr merge <repo> <n> --head <id> [--squash] [--delete-branch] | close <rep | |||||
| 68 | ermite web login # prints a one-time sign-in link (60 s) | 68 | ermite web login # prints a one-time sign-in link (60 s) | ||
| 69 | ermite web logout --all # signs every browser out | 69 | ermite web logout --all # signs every browser out | ||
| 70 | ermite signing-key show # public key and allowed_signers line of squash commits | 70 | ermite signing-key show # public key and allowed_signers line of squash commits | ||
| 71 | - | ermite config show | set <url|token.cmd> <value> | unset <key> # the CLI config file | 71 | + | ermite config show [--json] | set <url|token.cmd> <value> | unset <key> # the CLI config file |
| 72 | ermite version # client and server, warns about missing server features | 72 | ermite version # client and server, warns about missing server features | ||
| 73 | ermite watch [repo] [--json] # follows events, reconnects and resumes | 73 | ermite watch [repo] [--json] # follows events, reconnects and resumes | ||
| 74 | ``` | 74 | ``` | ||
M skills/ermite/CLI.md +1 -1
| @@ -78,7 +78,7 @@ Merge request JSON: `repo`, `number`, `title`, `description`, `source_branch`, ` | |||
| 78 | 78 | |---|---| | |
| 79 | 79 | | `serve` | configured by `ERMITE_*` environment variables only (see the project README) | | |
| 80 | 80 | | `version [--json]` | client version; with a server URL (`ERMITE_URL` or the config file), the server version and features | | |
| 81 | - | | `config show` / `config set <url\|token.cmd> <value>` / `config unset <key>` | the CLI config file; `token.cmd` is a command that prints the token (any secret manager), never the token itself; `show` never runs it | | |
| 81 | + | | `config show [--json]` / `config set <url\|token.cmd> <value>` / `config unset <key>` | the CLI config file; `token.cmd` is a command that prints the token (any secret manager), never the token itself; `show` never runs it | | |
| 82 | 82 | | `signing-key show` | public key and `allowed_signers` line to check squash commits with `git verify-commit` | | |
| 83 | 83 | | `web login [--json]` | one-time sign-in link (about 60 s); needs the admin token or a token with every scope and no repository list; the link is a secret | | |
| 84 | 84 | | `web logout --all` | signs every browser out | | |
| @@ -78,7 +78,7 @@ Merge request JSON: `repo`, `number`, `title`, `description`, `source_branch`, ` | |||||
| 78 | |---|---| | 78 | |---|---| | ||
| 79 | | `serve` | configured by `ERMITE_*` environment variables only (see the project README) | | 79 | | `serve` | configured by `ERMITE_*` environment variables only (see the project README) | | ||
| 80 | | `version [--json]` | client version; with a server URL (`ERMITE_URL` or the config file), the server version and features | | 80 | | `version [--json]` | client version; with a server URL (`ERMITE_URL` or the config file), the server version and features | | ||
| 81 | - | | `config show` / `config set <url\|token.cmd> <value>` / `config unset <key>` | the CLI config file; `token.cmd` is a command that prints the token (any secret manager), never the token itself; `show` never runs it | | 81 | + | | `config show [--json]` / `config set <url\|token.cmd> <value>` / `config unset <key>` | the CLI config file; `token.cmd` is a command that prints the token (any secret manager), never the token itself; `show` never runs it | |
| 82 | | `signing-key show` | public key and `allowed_signers` line to check squash commits with `git verify-commit` | | 82 | | `signing-key show` | public key and `allowed_signers` line to check squash commits with `git verify-commit` | | ||
| 83 | | `web login [--json]` | one-time sign-in link (about 60 s); needs the admin token or a token with every scope and no repository list; the link is a secret | | 83 | | `web login [--json]` | one-time sign-in link (about 60 s); needs the admin token or a token with every scope and no repository list; the link is a secret | | ||
| 84 | | `web logout --all` | signs every browser out | | 84 | | `web logout --all` | signs every browser out | | ||