1# Tokens
2
3```sh
4ermite token create <label> [--preset …] [--scope …] [--repo …] [--branch-prefix …] [--expires 30d]
5ermite token list
6ermite token revoke <id>
7```
8
9The secret is printed once. Presets and `--scope` add up. The full scope list is in [`skills/ermite/CLI.md`](../skills/ermite/CLI.md).
10
11| Preset | For |
12|---|---|
13| `cli` | every scope, the owner's daily use |
14| `agent` | `repo:write`, `mr:write` |
15| `ci` | `repo:read` |
16| `runner` | `runner:register`: a runner host. It can read the code and secrets of every repository, so give it only to runners you operate |
17
18## Branch-limited tokens
19
20For an AI agent that should propose changes, not publish them:
21
22```sh
23ermite token create claude --preset agent --scope repo:read --repo myrepo --branch-prefix agent/claude/
24```
25
26`--branch-prefix` is repeatable (up to 8), each ending with `/`.
27
28The token **can**:
29
30- push, force-push and delete branches under its prefixes;
31- open, comment on and close merge requests;
32- with `mr:merge`, merge into a branch under its prefixes;
33- read CI runs, logs and checks; with `ci:write`, cancel and re-run runs of its own branches;
34- create tokens whose prefixes lie within its own.
35
36The token **cannot**:
37
38- push any other ref (`main`, other branches, tags, notes). The whole push is refused and the message names the ref;
39- create, delete or configure a repository;
40- open web sessions or get owner rights, even with every scope;
41- manage runners, even with `runner:register`;
42- get trusted CI runs (no secrets). See [CI trust](ci.md#trust).
43
44`ermite token list` shows a `branches` column (`all` when unlimited); `--json` has `branch_prefixes`.