README
¶
anvil
An AXI-compliant CLI for Git forges — GitHub, GitLab, Forgejo — built for AI agents.
Quick Start
go install github.com/tnikic/anvil/cmd/anvil@latest
anvil auth set github.com <token>
anvil issue list
anvil detects the host and repo from your git remote. Pass --host and --repo to override.
Agent Skill
anvil ships an agent skill so AI harnesses know how to use it:
anvil skills install
The skill is extracted to ~/.agents/skills/anvil/SKILL.md, version-locked to your binary. Run anvil skills status to check, anvil skills update to refresh after an upgrade, and anvil skills uninstall to remove.
What it does
anvil normalizes GitHub, GitLab, and Forgejo behind one interface. Issue labels, PR stacks, and relationship graphs work the same way regardless of which forge you point at.
| Group | Operations |
|---|---|
issue |
list, view, create, update, close, reopen, comment, and relationship management (blocks, blocked-by, parent, children) |
pr |
list, view, create (with stack tracking), merge |
label |
list, create, update, delete |
auth |
status, set, unset |
skills |
install, status, update, uninstall |
anvil outputs TOON on stdout — a structured, line-oriented format agents parse efficiently — and writes human-readable help to stderr. Every error includes a help: line with the next action to take.
Index
- Make targets: run
make helpfor the full list
Credits
anvil is built on the AXI design principles by Kun Chen — a set of 10 agent-ergonomic standards that treat token budget as a first-class constraint. The TOON output format, the help: line in every error, and the structured confirmation messages all trace back to that work.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
anvil
command
|
|
|
skillgen
command
Command generate renders SKILL.md from internal/content and writes it to the specified output path.
|
Command generate renders SKILL.md from internal/content and writes it to the specified output path. |
|
internal
|
|
|
auth
Package auth manages authentication token storage for anvil.
|
Package auth manages authentication token storage for anvil. |
|
commands/blocking
Package blocking provides client-side filtering of issues by blocking status for the issue list command.
|
Package blocking provides client-side filtering of issues by blocking status for the issue list command. |
|
content
Package content is the single source of truth for agent-facing text shared between the dashboard and the skill generator.
|
Package content is the single source of truth for agent-facing text shared between the dashboard and the skill generator. |
|
forge/forgejo
Package forgejo implements the forge.Forge interface backed by code.gitea.io/sdk/gitea.
|
Package forgejo implements the forge.Forge interface backed by code.gitea.io/sdk/gitea. |
|
forge/github
Package github implements the forge.Forge interface backed by google/go-github.
|
Package github implements the forge.Forge interface backed by google/go-github. |
|
forge/gitlab
Package gitlab implements the forge.Forge interface backed by gitlab.com/gitlab-org/api/client-go.
|
Package gitlab implements the forge.Forge interface backed by gitlab.com/gitlab-org/api/client-go. |
|
forge/template
Package template provides shared helper types for forge adapters.
|
Package template provides shared helper types for forge adapters. |
|
format
Package format provides TOON output formatting for the anvil CLI.
|
Package format provides TOON output formatting for the anvil CLI. |
|
skillgen
Package skillgen renders SKILL.md from the content package.
|
Package skillgen renders SKILL.md from the content package. |
|
skills
Package skills provides embedded skill files for distribution via `anvil skills install`.
|
Package skills provides embedded skill files for distribution via `anvil skills install`. |
|
stack
Package stack implements PR stack tracking — parsing, ordering, renumbering, and diagnosing linear chains of dependent PRs identified by title prefixes.
|
Package stack implements PR stack tracking — parsing, ordering, renumbering, and diagnosing linear chains of dependent PRs identified by title prefixes. |