v0.17.0 ab8e178

SKILL.md RawHistoryFolder

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

  1. List: ermite mr list <repo> --json.
  2. Read: ermite mr show <repo> <n> --diff --json. Keep head_id; take line numbers from the hunks.
  3. Comment on a line: ermite mr comment <repo> <n> -m "text" --path <file> --line <n> --side new. Without --path the comment is general. The line must appear in the diff.
  4. Merge only when asked: ermite mr merge <repo> <n> --head <head_id>, with --squash for one commit signed by the server and --delete-branch to delete the source branch afterwards.

The merge is refused when the branch moved since head_id (review again) or when the target is not an ancestor of the head (rebase and push again). The repository may allow only one merge mode.

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), ci (read), cli (everything). Add --scope mr:merge to let an agent 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, comments). 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`. Without `--path` the comment is general. The line must appear in the diff.
394. Merge only when asked: `ermite mr merge <repo> <n> --head <head_id>`, with `--squash` for one commit signed by the server and `--delete-branch` to delete the source branch afterwards.
40
41The merge is refused when the branch moved since `head_id` (review again) or when the target is not an ancestor of the head (rebase and push again). The repository may allow only one merge mode.
42
43Open one: `ermite mr create <repo> --source <branch> --title "..."`. After new pushes, `mr show --since-last-read` shows only what changed since `--mark-read`.
44
45## Tokens
46
47```sh
48ermite token create my-agent --preset agent --repo <repo> --expires 30d
49```
50
51The secret is printed once. Presets: `agent` (push, open and comment on merge requests), `ci` (read), `cli` (everything). Add `--scope mr:merge` to let an agent merge. A token can never grant more than the token that creates it. Full scope list: [CLI.md](CLI.md).
52
53## Follow events
54
55`ermite watch [repo] --json` prints one JSON object per event (pushes, repositories, merge requests, comments). It reconnects and resumes on its own; a `gap` event means some events were lost, so reload the state.
56
57## Run a server
58
59```sh
60token=$(head -c 32 /dev/urandom | base64)   # the root credential: store it safely
61docker run -d -p 127.0.0.1:7341:7341 -v ermite-data:/data \
62  -e ERMITE_PUBLIC_URL=https://git.example.com -e ERMITE_ADMIN_TOKEN="$token" <ermite-image>
63```
64
65- Required: `ERMITE_DATA_DIR` (the image uses `/data`), `ERMITE_PUBLIC_URL`, `ERMITE_ADMIN_TOKEN` (32+ characters). It needs git 2.45 or newer.
66- Put TLS on a reverse proxy and list its network in `ERMITE_TRUSTED_PROXIES`.
67- Health check: `GET /-/health`.
68- Owner web access: `ermite web login` prints a one-time link (about 60 s, 12 h session).
69- If a page or a read looks wrong, set `ERMITE_GIT_READER=cli` and restart: every read then uses the `git` binary.
70
71## Output conventions
72
73`--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.
74
75Every command, flag, scope and JSON field: [CLI.md](CLI.md).

Keyboard shortcuts

Single-key shortcuts are on. ctrl k and esc work whatever this says.

ctrl k :
go to a section, branch, tag, file or repository
?
this list
j k
move the row cursor down / up
enter
open the row under the cursor; on Files, a directory opens or closes in place
↑ ↓ ← → home end
in the file tree (focus on a row): previous / next row, close / open a directory or go to its parent / first entry, first / last row. They never open a file
l h
on Files: open a directory or a file / close a directory or go up to its parent, then to the parent page. Elsewhere: into the side panel (on a merge request, its files) / back to the content; there j k move between its controls
g g G
first / last row
/
filter the list; on Files, find a file anywhere in the repository (esc clears, enter opens the best match)
b
switch branch or tag
g s g f g c g b g m g i g r g a
tabs: summary, files, commits, branches & tags, merge requests, issues, releases, actions (when available)
g h
home
w
wide mode: use the whole width of the screen, or not (remembered)
y
copy a permalink pinned to the commit
d u x
diff: split / unified / collapse or expand all
e E
diff: the whole file in view / every file, with the lines the hunks hide
n
merge request: next note in the diff
esc
close a dialog, leave a field

Branches 2

Tags 44

↑↓ moveenter openesc close