forgejo-axi

Agent-facing, non-interactive CLI boundary for Forgejo pull request lifecycles. It emits concise TOON by default and the same stable data model as JSON with --json.

Install

Requires Node.js 20 or newer.

npm install -g forgejo-axi

Or run it without installing:

npx forgejo-axi status

From source

Building from a checkout also needs an openssl executable for the ephemeral custom-CA HTTPS test.

npm ci
npm run build
npm link

Agent skill

skills/forgejo-axi/SKILL.md is a committed Agent Skill describing the complete command catalog, environment configuration, token rules, and non-interactive behavior. Install it into an agent with:

npx skills add escidmore/forgejo-axi --skill forgejo-axi -g

The published package ships this same file, so installing forgejo-axi from npm brings it along. Installing the skill on its own installs guidance only; it does not install the CLI runtime, which comes from the install above. The file is generated by npm run gen:skill: its command catalog comes from src/help.ts, the same help text the CLI serves on --help, and the guidance around that catalog from src/skill.ts. npm run check fails when the committed file drifts from either.

Configure

export FORGEJO_BASE_URL=https://forgejo.example/git
export FORGEJO_REPOSITORY=owner/repo
export FORGEJO_TOKEN_FORGEJO_2E_EXAMPLE=...
forgejo-axi status

For unattended processes that inherit HOME but not shell variables, configure a host in ~/.config/forgejo-axi/hosts.json:

install -d -m 700 "$HOME/.config/forgejo-axi"
touch "$HOME/.config/forgejo-axi/hosts.json"
chmod 600 "$HOME/.config/forgejo-axi/hosts.json"

{
  "forgejo.example": {
    "base_url": "https://forgejo.example/git",
    "token": "..."
  }
}

The top-level key is the URL host, including a non-default port. A single entry supplies the default base URL; select among multiple entries with --base-url or FORGEJO_BASE_URL. The file must be a regular file with mode 0600.

Tokens resolve from --token-env NAME, then FORGEJO_TOKEN_<HOST_KEY>, then FORGEJO_TOKEN when the base URL came from FORGEJO_BASE_URL, then the matching hosts-file entry. Host keys hex-encode punctuation (forgejo.example becomes FORGEJO_2E_EXAMPLE) to prevent look-alike hosts from sharing credentials. Tokens are never accepted as values on the command line or emitted. FORGEJO_TIMEOUT_MS configures request timeouts; FORGEJO_CA_FILE supplies a replacement CA trust bundle rather than extending the platform store.

Pull request lifecycle

forgejo-axi repo view --repo owner/repo
forgejo-axi pr find --repo owner/repo --head feature --base main
forgejo-axi pr list --repo owner/repo --fields number,title,state,head
forgejo-axi pr view --repo owner/repo 42 --full
forgejo-axi pr history list --repo owner/repo 42
forgejo-axi pr history detail --repo owner/repo 42 --history-id 249
forgejo-axi pr reviews --repo owner/repo 42 --full
forgejo-axi pr diff --repo owner/repo 42
forgejo-axi pr create --repo owner/repo --title 'Add feature' --head feature --base main
forgejo-axi pr create --repo owner/repo --title 'Add feature' --head feature --base main --body-file ./body.md
cat body.md | forgejo-axi pr update --repo owner/repo 42 --body-file -
forgejo-axi pr checks --repo owner/repo 42 --json
forgejo-axi pr mergeability --repo owner/repo 42
forgejo-axi pr merge --repo owner/repo 42 --expected-head abc123 --method squash
forgejo-axi pr merged --repo owner/repo 42

pr create and pr update reconcile existing state instead of duplicating mutations. Use either --body or --body-file PATH|-; file and stdin bodies are forwarded verbatim. pr merge requires the expected head SHA and sends Forgejo's atomic head_commit_id; repeated calls return merged-state proof. Empty statuses are reported: 0, state: none, not success, and missing required contexts never pass.

pr reviews and pr diff are read-only. Reviews come back with their verdicts and the inline comments anchored to the file and position each one marks, and the diff is the one the forge generates, so no pull ref has to be fetched. Submitting, dismissing, and deleting reviews stay on the api path.

pr history and issue history read Forgejo's content-history records from the web root, not the raw API. The default operation is list and the default --comment-id 0 addresses the description/body; pass a comment id to inspect a comment's history. detail returns reconstructed before and after text and keeps raw diff HTML out unless --raw is explicit. soft-delete is never interactive and requires --yes; it checks Forgejo's canSoftDelete permission first and reports already-deleted revisions as idempotent no-ops.

Lists fetch up to 100 Forgejo pages of 50 rows (5000 rows) and report completeness in page_info. TOON displays 30 rows by default and hints at --full when truncated; JSON displays every fetched row, and --limit is rejected with --json. Pull request lists use four fields by default and accept --fields LIST|all.

Label taxonomy

forgejo-axi label list --repo owner/repo --full
forgejo-axi label create --repo owner/repo bug --color '#d73a4a' --description 'Something is broken'
forgejo-axi label edit --repo owner/repo bug --name defect --color '#b60205'
forgejo-axi label delete --repo owner/repo wontfix

Labels are addressed by name; the numeric id is resolved for you. An unknown name is LABEL_NOT_FOUND and a duplicated name is LABEL_AMBIGUOUS, both usage errors that point at label list. label create reconciles an existing label of that name instead of duplicating it, and label edit --name renames in place so the label keeps its issue assignments.

Issue loop

forgejo-axi issue list --repo owner/repo --label bug --state open
forgejo-axi issue view --repo owner/repo 7 --full
forgejo-axi issue history overview --repo owner/repo 7
forgejo-axi issue history list --repo owner/repo 7 --comment-id 17
forgejo-axi issue create --repo owner/repo --title 'Race in scheduler' --label bug --milestone v1.0
forgejo-axi issue edit --repo owner/repo 7 --label bug,triage --assignee robot
forgejo-axi issue comment --repo owner/repo 7 --body 'Reproduced on 15.0.5'
forgejo-axi issue close --repo owner/repo 7 --comment 'Fixed in #42'
forgejo-axi issue reopen --repo owner/repo 7

Labels and milestones are addressed by name and resolved before anything is mutated, so an unknown name is a usage error rather than a half-applied edit or a filter Forgejo silently drops; assignee usernames go to Forgejo, which validates them. issue list returns issues only; pr list covers pull requests. issue edit sends only the fields that differ and reports updated=false when there is nothing to change. issue close --comment posts the comment before the state change. issue comment also accepts a pull request number, because Forgejo serves pull request discussion through the same endpoint.

Raw API and capabilities

forgejo-axi api GET 'repos/owner/repo/pulls?state=open'
forgejo-axi api GET repos/owner/repo/pulls --paginate --full
forgejo-axi api PATCH repos/owner/repo/pulls/42 --data '{"title":"New title"}'

status probes the runtime Swagger document rather than inferring features from the version. Forgejo 15.0.5 is supported and reports Actions job logs unavailable; Forgejo 16.x reports them only when the route is actually advertised. Unavailable logs are never treated as failed commit-status gating.

Self-hosted URLs may contain ports and path prefixes. Plaintext HTTP is restricted to loopback whether or not a token is configured, redirects must remain same-origin, and credentials, query strings, fragments, encoded separators, and dot segments are rejected in base URLs.

See docs/contract.md for the machine-output compatibility contract and run forgejo-axi --help for the complete command surface.

Development

npm run check
npm pack --dry-run
npm run verify

Tests use local fake HTTP/HTTPS servers and versioned Forgejo 15/16 fixtures; they do not require or mutate a live Forgejo instance. docs/live-test-matrix.md defines the 15.0.5 and 16.x live lanes, which run against real hosts and are required before changing API requests, response handling, or fixtures. CONTRIBUTING.md covers pointing them at your own Forgejo instances.

npm run verify is the completion check: it clones the committed tree into a temporary directory, runs npm ci, npm run check, and npm pack --dry-run there, installs the result into a throwaway prefix to run --help, --version, and the unconfigured home view, and installs the agent skill into a throwaway agent home to prove an installer finds it by the name forgejo-axi. It refuses to run against a dirty working tree, because it clones HEAD and can only speak for that commit. It reaches npm for dependencies and the skill installer, never a Forgejo host, and writes nothing outside its temporary directory apart from the shared npm cache.