Guides 1 min read
Running Afara in CI: a practical guide
Every command except the interactive shell works without a terminal. Here is how to fail a build when the code does something the ticket doesn't describe.
Afara Engineering, Engineering team
Afara’s CLI is built to run unattended. Without a terminal, every command behaves predictably:
afaraprints help instead of opening the interactive shell.afara generateuses all pending commits unless you pass--commits.afara linkrequires--issue.afara modellists the choices instead of asking, and commands that need a model use the backend’s default if none is set.
The check
The most useful CI step is a single line:
afara compare "card payment" --fail-on extra--fail-on takes extra, missing, reordered or any. The command exits with a non-zero status while open findings of that kind exist. Findings someone has already accepted or resolved don’t count, so the gate only fires on things a person hasn’t looked at.
What the runner needs
- A credential. Sign in once with
afara auth loginand provide the resulting~/.config/afara/credentials(or$XDG_CONFIG_HOME/afara/credentials) to the runner as a secret. - An AI coding tool, installed and authenticated, for
generateandcompare: Claude Code, OpenAI Codex CLI or Gemini CLI. Choose one explicitly with--toolif more than one is installed. - The pushed commit in the clone.
compareruns your AI tool in a read-only checkout of the pushed commit so it can open the files the code wireframe cites. A shallow clone that doesn’t include it still works, but the judgement is made from the two graphs alone.
Too-thin stories
If the linked ticket describes fewer than four steps, there isn’t enough to compare. The result is recorded as too thin, with no AI involved, along with what the ticket is missing. It doesn’t fail the build, but it’s a good signal that the ticket needs work.