The anvil command-line tool drives Anvil from your terminal: repositories, branches, commits, issues, epics, pull requests, CI runs, releases, deployments, agents, self-hosted runners, SSH keys, and requirements. The same binary serves as both the CLI and the CI runner. This page is a per-command lookup. For installing and operating a runner, see runners.
Install
Install the binary with the install script:
curl -fsSL https://anvil.fangorn.io/runner/install.sh | sh
Verify the install and print the version:
anvil --version
To replace the binary with a newer build later, use the built-in updater — see update.
Authenticate
Log in to a server. With no flags, anvil auth login prompts for the server URL (default https://anvil.fangorn.io) and runs the OAuth device flow, opening your browser to confirm a code.
anvil auth login
To skip the device flow with a personal access token (useful in CI), pass --token:
anvil auth login --url https://anvil.fangorn.io --token <pat>
Generate the personal access token in the Anvil web UI under your account settings. The token is verified against the server before it is saved; a rejected token is not written. Confirm the active session at any time:
anvil auth status
Config file location
Credentials are written to config.json under your platform config directory:
| Platform | Path |
|---|---|
| macOS | ~/Library/Application Support/anvil/config.json |
| Linux | ~/.config/anvil/config.json (or $XDG_CONFIG_HOME/anvil/config.json) |
| Windows | %APPDATA%\anvil\config.json |
The file stores server_url, token, and default_repo. The runner keeps its own separate config at ~/.anvil-runner/config.json — see runners.
Environment variables
Environment variables take precedence over the config file, so CI can inject credentials without writing to disk.
| Variable | Effect |
|---|---|
ANVIL_SERVER_URL |
Overrides the stored server URL |
ANVIL_TOKEN |
Overrides the stored access token |
ANVIL_RUNNER_TOKEN |
Runner registration token, read by anvil runner configure |
Global flags
These flags apply to every command.
| Flag | Description |
|---|---|
--json |
Output JSON instead of human-readable tables and detail views. Applies to list and view subcommands. Useful for piping into jq. |
-h, --help |
Print help for the binary or any subcommand. |
-V, --version |
Print the version and exit. |
Append --json to scriptable commands:
anvil issue list --json | jq '.[].title'
anvil ci list --status failed --json | jq '.[].id'
The release list command takes --format table|json instead of the global --json flag.
Repository resolution
Most subcommands operate on a repository identified as org/repo (for example, fangorn/anvil). When you do not pass a repository explicitly, anvil resolves one in this order:
- An explicit
--repo fangorn/anvilflag (or a positionalorg/repoargument on commands that accept one). - The
origingit remote of the current directory, parsed from SSH (git@anvil.fangorn.io:fangorn/anvil.git) or HTTPS (https://anvil.fangorn.io/fangorn/anvil.git) URLs. - The
default_reposaved in your config file.
Set a default repository so bare repo-scoped commands resolve outside a git checkout:
anvil repo set-default fangorn/anvil
After that, commands such as anvil issue list and anvil ci list target fangorn/anvil with no extra flags.
auth
| Command | Flags | Description |
|---|---|---|
anvil auth login |
--url, --token, --no-browser |
Log in. With no flags, prompts for the URL and runs the device flow. --token skips the device flow; --no-browser prints the verification URL instead of opening it. |
anvil auth status |
— | Show the current server, a masked token, and the default repo. |
anvil auth logout |
— | Remove the stored credentials file. |
repo
| Command | Flags | Description |
|---|---|---|
anvil repo list |
--org, --limit (default 30) |
List repositories you can see across your orgs. --org is a client-side substring filter on the org slug. |
anvil repo view [org/repo] |
— | Show repository details. Repo resolves from the argument or git remote. |
anvil repo create |
--name (required), --org, --description, --visibility (default private; private/public) |
Create a repository. --org defaults to the org of the default repo. |
anvil repo clone <org/repo> [dir] |
— | Clone a repository over SSH using your configured server host. |
anvil repo set-default <org/repo> |
— | Save the default repository for subsequent commands. |
anvil repo create --name infra --org fangorn --visibility public
anvil repo clone fangorn/anvil
branch
| Command | Flags | Description |
|---|---|---|
anvil branch list [org/repo] |
— | List the repository’s branches with the SHA each points at. |
commit
| Command | Flags | Description |
|---|---|---|
anvil commit list [org/repo] |
--ref-name (default HEAD), --limit (default 20) |
List commits reachable from a branch or ref. |
anvil commit view <sha> |
--diff |
Show a commit using local git show. Without --diff it prints the diffstat only; --diff includes the patch. Run inside a checkout of the repository. |
anvil commit list --ref-name main --limit 50
anvil commit view 60a2098 --diff
issue
Issue numbers are positional. The repository resolves per Repository resolution or with --repo.
| Command | Flags | Description |
|---|---|---|
anvil issue list [org/repo] |
--state (default open; open/closed/all), --limit (default 30) |
List issues. |
anvil issue view <number> |
--repo |
View an issue. |
anvil issue create |
--title (required), --body, --epic, --parent, --repo |
Create an issue. --epic marks it as an epic; --parent (a number, #5, or org/repo#5) links it as a child and auto-marks the parent as an epic. --epic and --parent are mutually exclusive. |
anvil issue close <number> |
--repo |
Close an issue. |
anvil issue reopen <number> |
--repo |
Reopen a closed issue. |
anvil issue edit <number> |
--title, --body, --repo |
Edit the title or body. |
anvil issue comment <number> |
--body (required), --repo |
Add a comment. |
anvil issue comments <number> |
--repo |
List comments. |
anvil issue assign <number> |
--user-id (required), --repo |
Assign a user by ID. |
anvil issue unassign <number> |
--user-id (required), --repo |
Remove an assignee by ID. |
anvil issue links <number> |
--repo |
List cross-reference links. |
anvil issue link <number> |
--kind (required; blocks/parent-of/duplicate-of/relates-to), --target (required), --repo |
Link to another issue. --target is #N (same repo) or org/repo#N. |
anvil issue unlink <number> <link_id> |
--repo |
Remove a link by its ID. |
anvil issue milestones [org/repo] |
— | List milestones. Equivalent to anvil milestone list. |
anvil issue create-milestone |
--title (required), --description, --due-date (YYYY-MM-DD), --repo |
Create a milestone. Equivalent to anvil milestone create. |
anvil issue create --repo fangorn/anvil --title "Flaky CI on aarch64" --body "Pool queue overflow"
anvil issue link 42 --kind blocks --target fangorn/anvil#7
epic
Epics are issues with kind: epic that group related sub-issues through parent_of links. These commands wrap the same issue endpoints.
| Command | Flags | Description |
|---|---|---|
anvil epic list [org/repo] |
--state (default open; open/closed/all), --limit (default 50) |
List epics. |
anvil epic view <number> |
--repo |
View an epic with its progress and children. |
anvil epic children <number> |
--repo |
Print only the children list. |
anvil epic add-child <epic> <child> |
--repo |
Link a child issue to the epic. <child> is 5, #5, or org/repo#5. |
anvil epic remove-child <epic> <child> |
--repo |
Remove a child link. |
anvil epic mark <number> |
--unmark, --repo |
Mark an issue as an epic. --unmark demotes it back to a standard issue. |
anvil epic auto-close <number> |
--on, --off, --repo |
Toggle whether closing the last open child auto-closes the epic (and reopening a child auto-reopens it). Pass exactly one of --on or --off. |
anvil epic mark 100
anvil epic add-child 100 fangorn/anvil#7
anvil epic auto-close 100 --on
pr
| Command | Flags | Description |
|---|---|---|
anvil pr list [org/repo] |
--state (default open; open/closed/merged/all), --limit (default 30) |
List pull requests. |
anvil pr view <number> |
--repo |
View a pull request. |
anvil pr create |
--title (required), --base (required), --head, --body, --repo |
Create a pull request. --head defaults to the current git branch. |
anvil pr edit <number> |
--title, --body, --repo |
Edit the title or body. |
anvil pr close <number> |
--repo |
Close a pull request. |
anvil pr reopen <number> |
--repo |
Reopen a closed pull request. |
anvil pr merge <number> |
--strategy (default merge_commit; merge_commit/squash/rebase), --repo |
Merge a pull request. |
anvil pr review <number> |
--action (required; approve/request_changes/comment), --body, --repo |
Submit a review. |
anvil pr reviews <number> |
--repo |
List reviews. |
anvil pr comment <number> |
--file (required), --line (required), --body (required), --repo |
Add an inline comment on a file and line. |
anvil pr diff <number> |
--name-only, --remote (default origin), --repo |
Print the PR diff using local git. --name-only lists changed files only. |
anvil pr checkout <number> |
--remote (default origin), --repo |
Fetch and check out the PR’s head branch locally. Refuses to run with uncommitted changes. |
anvil pr create --repo fangorn/anvil --title "Bump ex_git_objectstore" --base main
anvil pr merge 268 --strategy squash
anvil pr review 268 --action approve --body "LGTM"
anvil pr diff and anvil pr checkout shell out to local git, so run them inside a checkout that has the server configured as a remote.
ci
The <id> for runs and jobs accepts either the short ID shown in listings or the full UUID.
| Command | Flags | Description |
|---|---|---|
anvil ci list [org/repo] |
--status (queued/running/passed/failed), --limit (default 20) |
List CI runs. |
anvil ci view <id> |
--repo |
View a run and its jobs. |
anvil ci run [org/repo] |
--sha, --branch, --repo |
Trigger a run. --branch defaults to the current git branch; omit --sha to let the server resolve the commit from the branch. |
anvil ci job-view <id> |
--no-follow, --repo |
Show a job and stream its build logs. --no-follow dumps existing logs without following. |
anvil ci cancel <id> |
--repo |
Cancel a running run. |
anvil ci secrets [org/repo] |
— | List CI secret names (values hidden). |
anvil ci set-secret |
--name (required), --value (required), --env, --repo |
Set a secret. --env scopes it to one environment. |
anvil ci delete-secret |
--name (required), --repo |
Delete a secret. |
anvil ci run --repo fangorn/anvil --branch main
anvil ci set-secret --name DEPLOY_KEY --value <key> --env production
CI runs are defined by the repository’s .anvil.yml. Jobs execute on self-hosted runners.
release
Releases are keyed by tag name.
| Command | Flags | Description |
|---|---|---|
anvil release list [org/repo] |
--format (table/json, default table) |
List releases. |
anvil release view <tag> |
--repo |
View a release and its assets. |
anvil release create |
--tag (required), --title, --body, --prerelease, --draft, --repo |
Create a release. --title defaults to the tag. |
anvil release update <tag> |
--title, --body, --draft (true/false), --prerelease (true/false), --repo |
Update release fields. |
anvil release delete <tag> |
--repo |
Delete a release. |
anvil release publish <tag> |
--repo |
Publish a draft release. |
anvil release upload <tag> <file> |
--name, --repo |
Upload an asset. --name overrides the stored filename. |
anvil release download <tag> <filename> |
--output, --repo |
Download an asset by filename. --output sets the destination path (default: current directory). |
anvil release assets <tag> |
--repo |
List release assets. |
anvil release delete-asset <tag> <asset_id> |
--repo |
Delete an asset by its short ID. |
anvil release changelog <base> <head> |
--repo |
Generate a changelog between two tags. |
anvil release create --tag v1.2.0 --title "v1.2.0" --body "Bug fixes"
anvil release upload v1.2.0 ./dist/anvil-linux-amd64
anvil release changelog v1.1.0 v1.2.0
deploy
Deployments and environments are repository-scoped.
| Command | Flags | Description |
|---|---|---|
anvil deploy list [org/repo] |
--env (required) |
List deployments for an environment. |
anvil deploy create |
--env (required), --ref (required), --description, --repo |
Create a deployment of a ref/branch/tag to an environment. |
anvil deploy status [org/repo] |
— | Show the current deployment status. |
anvil deploy env list [org/repo] |
— | List environments. |
anvil deploy env create |
--name (required), --repo |
Create an environment. |
anvil deploy env create --name production --repo fangorn/anvil
anvil deploy create --env production --ref v1.2.0 --description "Release 1.2.0"
anvil deploy list --env production
agent
AI agents are configured per repository. Triggering an agent starts a session; some actions wait for approval.
| Command | Flags | Description |
|---|---|---|
anvil agent list [org/repo] |
— | List agents available in the repository. |
anvil agent view <name> |
--repo |
Show an agent’s description, trigger, and model. |
anvil agent trigger <name> |
--prompt, --repo |
Start an agent run, optionally with a prompt. |
anvil agent sessions <name> |
--repo |
List sessions for an agent. |
anvil agent session <id> |
--repo |
View a session and its messages. |
anvil agent approve <id> |
--repo |
Approve a pending agent action. |
anvil agent reject <id> |
--repo |
Reject a pending agent action. |
anvil agent trigger reviewer --prompt "Review the open PRs" --repo fangorn/anvil
anvil agent approve 3f9a2b1c
label
| Command | Flags | Description |
|---|---|---|
anvil label list [org/repo] |
— | List the repository’s labels. |
anvil label create |
--name (required), --color (default #6b7280), --description, --repo |
Create a label. --color is a hex value such as #ff0000. |
anvil label add |
--issue (required), --name (required), --repo |
Add a label to an issue. |
anvil label remove |
--issue (required), --name (required), --repo |
Remove a label from an issue. |
anvil label create --name bug --color "#d73a4a" --description "Something is broken"
anvil label add --issue 42 --name bug
milestone
| Command | Flags | Description |
|---|---|---|
anvil milestone list [org/repo] |
— | List milestones with progress. |
anvil milestone view <id> |
--repo |
View a milestone by short ID or UUID. |
anvil milestone create |
--title (required), --description, --due-date (YYYY-MM-DD), --repo |
Create a milestone. |
anvil milestone create --title "v1.0" --due-date 2026-12-31 --repo fangorn/anvil
board
| Command | Flags | Description |
|---|---|---|
anvil board list [org/repo] |
— | List the repository’s board columns and the issues in each. Reports if the board feature is not enabled for the repository. |
runner
The runner subcommands manage a CI runner on the current machine, plus commands for listing and updating runners registered to an org or repo. Registering, listing, updating, and removing runners, and generating registration tokens, require an org or repo admin. See runners for the full operational guide.
| Command | Flags | Description |
|---|---|---|
anvil runner configure |
--url (required), --token, --name, --labels (default self-hosted), --work-dir, --parallel (default 1), --config |
Register this machine as a runner. The token comes from --token or ANVIL_RUNNER_TOKEN. --name defaults to the hostname; --work-dir defaults to ~/.anvil-runner/_work. |
anvil runner start |
--once, --ephemeral, --cleanup (default never; always/never/on-success), --config |
Poll for and execute jobs. --once runs one job; --ephemeral deregisters after one job. |
anvil runner status |
--config |
Show this machine’s runner configuration. |
anvil runner unconfigure |
--config |
Deregister from the server and remove the runner config. |
anvil runner service install |
--config |
Install the OS service (systemd on Linux, launchd on macOS). |
anvil runner service uninstall |
— | Remove the OS service. |
anvil runner service svc-start |
— | Start the service. |
anvil runner service svc-stop |
— | Stop the service. |
anvil runner service svc-restart |
— | Restart the service (to pick up an upgraded binary). |
anvil runner service svc-status |
— | Show service status. |
anvil runner token |
--org, --repo |
Generate a registration token for an org or a repo. Pass exactly one of --org or --repo. |
anvil runner list |
--org, --repo |
List runners registered to an org or repo. Pass exactly one of --org or --repo. |
anvil runner view <id> |
— | View runner details. |
anvil runner update <id> |
--labels, --name |
Update a runner’s labels or name. |
anvil runner remove <id> |
— | Deregister a runner by its ID. |
The runner stores its config at ~/.anvil-runner/config.json by default; override with --config.
anvil runner token --repo fangorn/anvil
anvil runner configure --url https://anvil.fangorn.io --token <token> --labels self-hosted,arm64
anvil runner start --cleanup on-success
ssh-key
These commands manage the SSH keys on your account used for git push and pull.
| Command | Flags | Description |
|---|---|---|
anvil ssh-key list |
— | List your SSH keys with fingerprints and last-used times. |
anvil ssh-key add |
--name (required), --key-file (required) |
Add a key. --key-file is the path to your public key (for example, ~/.ssh/id_ed25519.pub). |
anvil ssh-key remove <id> |
— | Remove a key by its ID. |
anvil ssh-key add --name "laptop" --key-file ~/.ssh/id_ed25519.pub
requirement
The requirement commands manage Anvil’s requirements and the traceability matrix. IDs follow REQ-<DOMAIN>-<NNN> and are repo-scoped; standards use STD-* and are org-scoped. The kind is inferred from the ID prefix, so a STD-* ID needs --organization while a REQ-* ID needs --repo.
| Command | Flags | Description |
|---|---|---|
anvil requirement list |
--status (draft/active/deprecated), --category, --repo, --organization, --kind (default requirement; requirement/standard/all), --framework, --mandatory |
List requirements (repo-scoped) or standards (org-scoped). --framework and --mandatory filter standards. |
anvil requirement view <id> |
--repo, --organization, --show-empty |
View a requirement or standard and its linked tests. --show-empty shows fields with no value. |
anvil requirement create |
--requirement-id (required), --title (required), --description, --category, --priority, --status, --parent-id, --repo, --organization, --source, --external-url, standards-only metadata |
Create a requirement (REQ-*) or standard (STD-*). |
anvil requirement update <id> |
--title, --description, --category, --priority (critical/high/medium/low), --status, --repo, --organization, --source, --external-url, standards-only metadata |
Update an existing requirement or standard. |
anvil requirement delete <id> |
--repo, --organization |
Soft-delete a requirement or standard. |
anvil requirement matrix |
--repo, --organization, --kind (default requirement; requirement/standard) |
Show the traceability matrix. |
anvil requirement status |
--repo, --strict, --strict-standards, --organization |
Coverage gate. Exits non-zero if uncovered requirements exist. --strict also fails on partial coverage. --strict-standards checks the org-wide standards gate and requires --organization. |
anvil requirement seed |
--repo, --clear |
Seed the 204 platform requirements. --clear removes existing requirements first. |
anvil requirement applicability list <id> |
--organization (required) |
List repositories opted into a standard. <id> is a STD-* ID. |
anvil requirement applicability add <id> |
--organization (required), --repo (required) |
Opt a repository into a standard (idempotent). --repo is the repository slug within the org. |
anvil requirement applicability remove <id> |
--organization (required), --repo (required) |
Opt a repository out of a standard (idempotent). --repo is the repository slug within the org. |
create and update accept additional metadata flags. --source (free-text source such as ADR-014) and --external-url apply to both kinds. The standards-only flags --framework, --citation, --framework-version, --authority, --effective-date, and --mandatory are accepted only on STD-* IDs.
anvil requirement create --requirement-id REQ-CI-030 --title "CI runs respect job dependencies" --category functional
anvil requirement status --repo fangorn/anvil
update
Replace the running binary with the latest release served by your configured server.
| Command | Flags | Description |
|---|---|---|
anvil update |
--check, --force, --no-verify |
Download and install the latest binary for your platform. --check reports whether an update is available without installing. --force reinstalls even when already current. --no-verify skips the SHA256 check of the download (not recommended). |
The updater downloads the build matching your OS and architecture, verifies its SHA256 against the server’s published checksums, and atomically replaces the current executable.
anvil update --check
anvil update
Next steps
- Get started — first checkout and push
- .anvil.yml — CI pipeline config
- runners — install and operate a self-hosted runner
- Git LFS — large file storage
- registry — OCI container registry
- webhooks — event delivery