CLI
Every autofeat command, with the flags the binary actually accepts.
Install the package and run autofeat. autofeat --version and autofeat -V print the version and exit. With no subcommand, the CLI prints help.
Commands below are the ones registered on the Typer app. Flags not listed here are not part of that command.
autofeat route
Route one GitHub webhook JSON file to a Decision. Exit 0 even when dispatch is false. Needs the network to read the journal unless --no-remote-state is set.
autofeat route --event ./event.json --event-name pull_request --explain
autofeat route --event ./event.json --output ./decision.json --no-remote-state| Flag | Meaning |
|---|---|
--event | Required. Webhook payload JSON. |
--event-name | pull_request, issue_comment, or workflow_dispatch. |
--config | Path to .autofeat/config.yml. Default: that file under the working directory. |
--output | Write Decision JSON here. Default: stdout. |
--explain | Print every guard as PASS, FAIL, or SKIPPED. |
--no-remote-state | Do not read the journal or sticky. Treat state as absent. |
autofeat exec
Execute a Decision and write <run-dir>/result.json. Exit 1 when result.ok is false or a blocking budget alert fired. A spend alert alone warns.
autofeat exec --decision ./decision.json --repo-dir .| Flag | Meaning |
|---|---|
--decision | Required. Decision JSON from route or simulate. |
--repo-dir | Checkout. Default . |
--run-dir | Artifact directory. Default <repo>/.autofeat/run. |
--config | Ignored. Policy comes from the decision snapshot, not this path. |
autofeat simulate
Same router as route, with no network and no GitHub writes. Use it to iterate on a fixture.
autofeat simulate --event ./event.json --state ./run-state.json --explain| Flag | Meaning |
|---|---|
--event | Required. Webhook payload JSON. |
--config | Config path. Default: .autofeat/config.yml under the working directory. |
--state | RunState JSON. Default: no prior state. |
--explain | Print every guard as PASS, FAIL, or SKIPPED. |
--event-name | Event name. Inferred from the payload when omitted. |
autofeat init
Actions path only. Writes .github/workflows/autofeat.yml and .autofeat/config.yml, creates labels, and runs doctor. See Actions path.
| Flag | Meaning |
|---|---|
--repo-dir | Checkout. Default . |
--force | Overwrite existing workflow or config. |
--release | latest or vX.Y.Z. Default latest. |
autofeat doctor
Preflight for the Actions path. Exit 1 if any row is FAIL. --repo-dir defaults to .. --json prints JSON instead of a table.
A banner is printed above the rows, not as a row:
EFFECTIVE POLICY: merge_mode=stop_before_merge dry_run=trueWhen dry_run is false and merge_mode is auto, the banner adds: WARNING: dry_run=false with merge_mode=auto permits unattended merges.
Row order:
| Row | What it checks |
|---|---|
config | .autofeat/config.yml loads. |
workflow | .github/workflows/autofeat.yml exists and its uses: pin is a SHA or a version tag. Missing file is FAIL. |
app_credentials | AUTOFEAT_APP_ID and AUTOFEAT_APP_PRIVATE_KEY are set. |
signing_key | AUTOFEAT_SIGNING_KEY when signatures are required. |
app_token | Installation token can list repositories. |
labels | The four labels exist. |
merge_target | The configured base branch exists. |
auto_approve | Branch protection versus auto_approve. See below. |
state_ruleset | Ruleset autofeat-state-refs is active and has no bypass actors. Missing, or not visible to the token, is WARN when dry_run is true and FAIL otherwise. Bypass actors the token cannot see are WARN. |
budget_alert | PASS when alert_usd <= budget.usd. The schema already rejects a larger alert, so a loaded config passes this row. |
budget_estimate | PASS with budget.usd, alert_usd, and the note costs are estimated from token counts. |
policy_mode | PASS, or WARN when mode is full and dry_run is false. |
allowed_actions | The derived or configured action list. |
policy_reviewer | Reviewer provider and model. Null means no override. |
agent_uid | PASS when the agent UID is separate. WARN when allow_same_uid is true. |
auto_approve row: false is PASS. True with an unknown approval count is WARN (could not read branch protection). True with a required approval count above 0 is WARN. True with zero required approvals is PASS. The hint when approvals are required: the App cannot approve a pull request it authored.
On a hosted repository that correctly has no workflow, workflow FAILs and app_credentials FAILs. That is the Actions-path preflight, not a sign that the App install is broken.
autofeat setup-app
Create a private GitHub App for the Actions path, or verify an existing one. This is not how you install the hosted App autofeat-axc.
| Flag | Meaning |
|---|---|
--name | New App name. |
--repo | owner/name that receives secrets. |
--force | Overwrite. |
--timeout | Seconds. Default 600. |
--verify-app | App id to verify. Does not create an App and does not write secrets. |
--key-path | PEM for --verify-app. |
Exit 2 means installation or repository access was not verified.
autofeat hosted
Serve the receiver. --check prints the hosted config JSON and exits. No other flags.
autofeat worker
Pull Pub/Sub and run one container per job. No flags.
autofeat hosted-run
Container entrypoint: verify, check out, supervise. No flags.
autofeat directive
render
Print a markdown directive. --sign HMACs it with AUTOFEAT_SIGNING_KEY.
| Flag | Meaning |
|---|---|
--action | Required. plan, implement, test, review, gate, merge, or halt. |
--method | Optional. Default is the action's default method. |
--turn | Integer. Default 0. |
--body-file | Markdown body. Default empty. |
--sign | Sign with AUTOFEAT_SIGNING_KEY. |
--repo | Binding owner/name. |
--pr | Binding pull request number. |
--head-sha | Binding head SHA. |
parse
autofeat directive parse --file ./comment.md. Prints JSON. A file that is not a directive prints not a directive and exits 0.
verify
autofeat directive verify --file ./comment.md. Exit 0 when the HMAC is valid, exit 1 when it is not. The reason goes to stderr. Uses AUTOFEAT_SIGNING_KEY.
autofeat reconcile
Operator only. Use this when the journal ref is missing or GitHub cut the commit message. A repository owner cannot repair that from a label. See Troubleshooting.
prepare
Print a signed reconciliation request. Redirect it to a file and read it before apply.
autofeat reconcile prepare \
--repo owner/repo \
--pr 123 \
--usd 1.5 \
--tokens 100000 \
--minutes 12 \
--reason "ledger rebuilt from check-run annotations"| Flag | Meaning |
|---|---|
--repo | Required. owner/name. |
--pr | Required. Pull request number, at least 1. |
--usd | Required. Confirmed cumulative USD, at least 0. |
--tokens | Required. Confirmed cumulative tokens, at least 0. |
--minutes | Required. Confirmed cumulative minutes, at least 0. |
--reason | Required. Why this correction is right. |
--correct-measured | Lower an over-charged measured ledger. Each total must be <= the current total. |
--adopt-truncated | Adopt the signed sticky when GitHub cut the journal message at 65536 characters. Totals stay as restated. |
--operator | Required together with --correct-measured or --adopt-truncated. |
--correct-measured and --adopt-truncated cannot be combined.
apply
autofeat reconcile apply --repo owner/repo --pr 123 --file ./request.mdVerifies the signed request, writes the corrected totals, and records the audit. --file must exist and be readable.