name: ermite description: Explains how to use an ermite Git forge and its CLI - clone and push over HTTPS, repositories, tokens and scopes, merge requests (review, comment, merge), live events, and running the server. Use when the user mentions ermite, runs `ermite` commands, pushes to or reviews on an ermite server, or self-hosts one.

ermite

ermite is a single-user Git forge in one binary. ermite serve runs the server; every other ermite command is a client that talks to a running server over its API. The owner holds the admin token and creates scoped tokens for themselves, agents and CI.

Connect

export ERMITE_URL=https://git.example.com
export ERMITE_TOKEN=ermite_...        # optional for public reads
ermite version                        # client and server versions, warns about missing features
ermite repo list

Instead of exporting them, the owner can keep url and a token.cmd (a command that prints the token, such as pass show ermite/token) in ~/.config/ermite/config; as an agent, set ERMITE_TOKEN or point ERMITE_CONFIG at your own file.

Never print a token, commit it, log it or paste it into a chat. Prefer a Git credential helper to a token in a URL. Use https://: a token sent over plain http:// to a remote host triggers a warning.

Git

git clone https://git.example.com/<repo>.git                 # public: no credentials
git push https://git.example.com/<repo>.git main             # password = token, username ignored

Pushing to a name that does not exist creates a private repository (needs repo:write).
Names are lowercase [a-z0-9._-], 1 to 100 characters.
Private repositories need repo:read to clone or browse.

Review a merge request

List: ermite mr list <repo> --json.
Read: ermite mr show <repo> <n> --diff --json. Keep head_id; take line numbers from the hunks.
Comment on a line: ermite mr comment <repo> <n> -m "text" --path <file> --line <n> --side new; --line 10-14 covers a range on one side. Without --path the comment is general. The line must appear in the diff. Notes are Markdown; ^N refers to note N.
End a review with a verdict (needs mr:review): --approve or --request-changes, alone or with a message. Verdicts are informative and cannot be edited; a new verdict replaces the previous one.
Merge only when asked: ermite mr merge <repo> <n> --head <head_id>, with --mode squash for one commit or --mode merge for a merge commit (both signed by the server's key, see ermite signing-key show) and --delete-branch to delete the source branch afterwards.

The merge is refused when the branch moved since head_id (review again) or, for fast-forward, when the target is not an ancestor of the head (rebase and push again, or use squash/merge), or when squash/merge conflict. ermite mr show prints the mergeability line (up to date, behind by N, conflict with paths). The repository may allow only some merge modes.

Act on a review

Notes are visible as soon as they are written, so a review is not finished until its verdict. Act on a verdict, not on each note (ermite watch --json shows verdict on the comment_added event).

On changes_requested: run ermite mr show <repo> <n> --json, read the open threads (roots with resolved false and their replies), fix the code, push, then answer each thread with ermite mr comment <repo> <n> --reply <id> -m "Fixed in ^N". Leave resolving to the reviewer: do not run mr resolve on their threads. Edit or delete only your own notes (mr edit-comment, mr delete-comment).

An approval is stale after a push; changes requested stay until the reviewer gives a new verdict.

ermite mr create and ermite mr close print a confirmation followed by the full merge request web URL on its own line. With --json, merge request objects (create, show, list, close and merge) include url alongside the other fields.

Open one: ermite mr create <repo> --source <branch> --title "...". After new pushes, mr show --since-last-read shows only what changed since --mark-read.

Tokens

ermite token create my-agent --preset agent --repo <repo> --expires 30d

The secret is printed once. Presets: agent (push, open and comment on merge requests; no verdicts), ci (read), cli (everything). Add --scope mr:review to let an agent give verdicts, --scope mr:merge to let it merge. A token can never grant more than the token that creates it. Full scope list: CLI.md.

Follow events

ermite watch [repo] --json prints one JSON object per event (pushes, repositories, merge requests, notes: added, edited, deleted, resolved). It reconnects and resumes on its own; a gap event means some events were lost, so reload the state.

Run a server

token=$(head -c 32 /dev/urandom | base64)   # the root credential: store it safely
docker run -d -p 127.0.0.1:7341:7341 -v ermite-data:/data \
  -e ERMITE_PUBLIC_URL=https://git.example.com -e ERMITE_ADMIN_TOKEN="$token" <ermite-image>

Required: ERMITE_DATA_DIR (the image uses /data), ERMITE_PUBLIC_URL, ERMITE_ADMIN_TOKEN (32+ characters). It needs git 2.45 or newer.
Put TLS on a reverse proxy and list its network in ERMITE_TRUSTED_PROXIES.
Health check: GET /-/health.
Owner web access: ermite web login prints a one-time link (about 60 s, 12 h session).
If a page or a read looks wrong, set ERMITE_GIT_READER=cli and restart: every read then uses the git binary.

Output conventions

--json prints stable field names, listed in each command's --help. Errors are one line on standard error (ermite: ...) with exit status 1. ermite completion bash|zsh|fish completes repository names.

Every command, flag, scope and JSON field: CLI.md.

source

1---
2name: ermite
3description: Explains how to use an ermite Git forge and its CLI - clone and push over HTTPS, repositories, tokens and scopes, merge requests (review, comment, merge), live events, and running the server. Use when the user mentions ermite, runs `ermite` commands, pushes to or reviews on an ermite server, or self-hosts one.
4---
5
6# ermite
7
8ermite is a single-user Git forge in one binary. `ermite serve` runs the server; every other `ermite` command is a client that talks to a running server over its API. The owner holds the admin token and creates scoped tokens for themselves, agents and CI.
9
10## Connect
11
12```sh
13export ERMITE_URL=https://git.example.com
14export ERMITE_TOKEN=ermite_...        # optional for public reads
15ermite version                        # client and server versions, warns about missing features
16ermite repo list
17```
18
19Instead of exporting them, the owner can keep `url` and a `token.cmd` (a command that prints the token, such as `pass show ermite/token`) in `~/.config/ermite/config`; as an agent, set `ERMITE_TOKEN` or point `ERMITE_CONFIG` at your own file.
20
21Never print a token, commit it, log it or paste it into a chat. Prefer a Git credential helper to a token in a URL. Use `https://`: a token sent over plain `http://` to a remote host triggers a warning.
22
23## Git
24
25```sh
26git clone https://git.example.com/<repo>.git                 # public: no credentials
27git push https://git.example.com/<repo>.git main             # password = token, username ignored
28```
29
30- Pushing to a name that does not exist creates a private repository (needs `repo:write`).
31- Names are lowercase `[a-z0-9._-]`, 1 to 100 characters.
32- Private repositories need `repo:read` to clone or browse.
33
34## Review a merge request
35
361. List: `ermite mr list <repo> --json`.
372. Read: `ermite mr show <repo> <n> --diff --json`. Keep `head_id`; take line numbers from the hunks.
383. Comment on a line: `ermite mr comment <repo> <n> -m "text" --path <file> --line <n> --side new`; `--line 10-14` covers a range on one side. Without `--path` the comment is general. The line must appear in the diff. Notes are Markdown; `^N` refers to note N.
394. End a review with a verdict (needs `mr:review`): `--approve` or `--request-changes`, alone or with a message. Verdicts are informative and cannot be edited; a new verdict replaces the previous one.
405. Merge only when asked: `ermite mr merge <repo> <n> --head <head_id>`, with `--mode squash` for one commit or `--mode merge` for a merge commit (both signed by the server's key, see `ermite signing-key show`) and `--delete-branch` to delete the source branch afterwards.
41
42The merge is refused when the branch moved since `head_id` (review again) or, for `fast-forward`, when the target is not an ancestor of the head (rebase and push again, or use `squash`/`merge`), or when `squash`/`merge` conflict. `ermite mr show` prints the `mergeability` line (up to date, behind by N, conflict with paths). The repository may allow only some merge modes.
43
44### Act on a review
45
46Notes are visible as soon as they are written, so a review is not finished until its verdict. Act on a verdict, not on each note (`ermite watch --json` shows `verdict` on the `comment_added` event).
47
48On `changes_requested`: run `ermite mr show <repo> <n> --json`, read the open threads (roots with `resolved` false and their replies), fix the code, push, then answer each thread with `ermite mr comment <repo> <n> --reply <id> -m "Fixed in ^N"`. Leave resolving to the reviewer: do not run `mr resolve` on their threads. Edit or delete only your own notes (`mr edit-comment`, `mr delete-comment`).
49
50An approval is stale after a push; changes requested stay until the reviewer gives a new verdict.
51
52`ermite mr create` and `ermite mr close` print a confirmation followed by the full
53merge request web URL on its own line. With `--json`, merge request objects
54(create, show, list, close and merge) include `url` alongside the other fields.
55
56Open one: `ermite mr create <repo> --source <branch> --title "..."`. After new pushes, `mr show --since-last-read` shows only what changed since `--mark-read`.
57
58## Tokens
59
60```sh
61ermite token create my-agent --preset agent --repo <repo> --expires 30d
62```
63
64The secret is printed once. Presets: `agent` (push, open and comment on merge requests; no verdicts), `ci` (read), `cli` (everything). Add `--scope mr:review` to let an agent give verdicts, `--scope mr:merge` to let it merge. A token can never grant more than the token that creates it. Full scope list: [CLI.md](CLI.md).
65
66## Follow events
67
68`ermite watch [repo] --json` prints one JSON object per event (pushes, repositories, merge requests, notes: added, edited, deleted, resolved). It reconnects and resumes on its own; a `gap` event means some events were lost, so reload the state.
69
70## Run a server
71
72```sh
73token=$(head -c 32 /dev/urandom | base64)   # the root credential: store it safely
74docker run -d -p 127.0.0.1:7341:7341 -v ermite-data:/data \
75  -e ERMITE_PUBLIC_URL=https://git.example.com -e ERMITE_ADMIN_TOKEN="$token" <ermite-image>
76```
77
78- Required: `ERMITE_DATA_DIR` (the image uses `/data`), `ERMITE_PUBLIC_URL`, `ERMITE_ADMIN_TOKEN` (32+ characters). It needs git 2.45 or newer.
79- Put TLS on a reverse proxy and list its network in `ERMITE_TRUSTED_PROXIES`.
80- Health check: `GET /-/health`.
81- Owner web access: `ermite web login` prints a one-time link (about 60 s, 12 h session).
82- If a page or a read looks wrong, set `ERMITE_GIT_READER=cli` and restart: every read then uses the `git` binary.
83
84## Output conventions
85
86`--json` prints stable field names, listed in each command's `--help`. Errors are one line on standard error (`ermite: ...`) with exit status 1. `ermite completion bash|zsh|fish` completes repository names.
87
88Every command, flag, scope and JSON field: [CLI.md](CLI.md).

SKILL.md RawHistoryFolder