How to Use the axi Command-Line Interface for Non-Interactive Automation

The axi sub-command in no-mistakes provides a fully automated Agent eXperience Interface that accepts flags, outputs structured TOON data, and supports CI/CD workflows through commands like axi run --yes, axi respond, and axi status.

The no-mistakes repository exposes the axi command-line interface specifically for automated drivers, scripts, and CI jobs that require non-interactive pipeline automation. Unlike the interactive TUI, every axi operation is driven solely by command-line flags and emits structured TOON output on stdout while routing diagnostics to stderr. This design enables you to integrate code review automation, gate approvals, and pipeline monitoring directly into your deployment scripts.

Architecture of the axi CLI

The axi implementation consists of a root command builder and specialized sub-commands that communicate via IPC with a background daemon.

Root Command and Sub-commands

In internal/cli/axi.go, the newAxiCmd function constructs the command tree, delegating to specific handlers for each operation. The architecture supports five primary sub-commands:

• axi run – Implemented in internal/cli/axi_drive.go via newAxiRunCmd, this command starts or attaches to pipeline runs.
• axi respond – Also in axi_drive.go, handles gate approvals through newAxiRespondCmd.
• axi status – Defined in internal/cli/axi_query.go via newAxiStatusCmd for read-only state inspection.
• axi logs – Implemented in axi_query.go through newAxiLogsCmd for streaming step logs.
• axi abort – Located in axi_drive.go via newAxiAbortCmd for cancellation operations.

Daemon IPC Communication

All commands rely on openAxiEnv (in axi.go) to establish an ipc.Client connection to the background daemon. The client executes RPC methods such as MethodGetActiveRun, MethodRespond, and MethodCancelRun defined in the internal/ipc/ package. This separation ensures that the CLI remains stateless while the daemon manages pipeline lifecycle and persistence.

Non-Interactive Workflow Commands

The axi command-line interface supports complete automation through flag-driven operations that never prompt for user input.

Starting Automated Runs with axi run

The axi run command serves as the entry point for automation. In internal/cli/axi_drive.go, the runAxiRun function parses flags including --intent, --skip, and --yes. When --yes is provided, the command auto-approves every gate and auto-fixes actionable findings without interaction.

The driveRun function implements the polling loop using drivePollInterval, handling gateResolution logic and detecting ciReadyToMerge states. If a run exists for the current branch and HEAD, the command re-attaches; otherwise, it pushes the current commit to the gate remote and creates a new run.

no-mistakes axi run --intent "refactor authentication" --yes --skip lint,docs

Responding to Gates Programmatically

When you need explicit control over gate approvals rather than auto-approval, use axi respond. The runAxiRespond function in axi_drive.go sends a Respond IPC request with parameters parsed by newAxiRespondCmd, including --action (approve|fix|skip), --step, and --findings.

This command integrates with external policy engines that evaluate TOON output before deciding on specific actions.

no-mistakes axi respond --action approve --step "security-scan"

Querying State with axi status and logs

For read-only automation, axi status and axi logs provide idempotent state inspection. Implemented in internal/cli/axi_query.go, these commands fetch run snapshots and stream step logs without side effects. The newAxiStatusCmd handler retrieves the current pipeline state, while newAxiLogsCmd accesses specific step outputs.

no-mistakes axi status | jq '.steps[] | select(.name=="test") | .status'
no-mistakes axi logs --step build

Aborting Runs

The axi abort command cancels running pipelines by branch or explicit run ID. The newAxiAbortCmd handler in axi_drive.go issues MethodCancelRun RPC calls to terminate runaway processes.

no-mistakes axi abort --run uuid-1234-5678

Implementing CI/CD Automation

Integrating axi into CI/CD pipelines requires understanding the TOON output format and exit code behavior.

Parsing TOON Output

axi emits structured TOON (JSON-like) data on stdout, enabling parsing with tools like jq. The output includes fields such as outcome, error, steps, and pr_url. When run or respond with --yes returns outcome=checks-passed, the PR is ready for merge.

OUTCOME=$(no-mistakes axi run --intent "add feature X" --yes | jq -r '.outcome')
if [ "$OUTCOME" = "checks-passed" ]; then
    echo "Ready for merge"
fi

Exit Codes and Error Handling

Commands return structured exit codes: 0 for success and 1 for failure. The emitError helper in axi.go consolidates error reporting, embedding messages in the TOON error field. Automation can distinguish between no-run states (exit 0 with help field) and run failures (exit 1 with error field).

Summary

• The axi command-line interface in no-mistakes provides non-interactive automation through the Agent eXperience Interface.
• Source files internal/cli/axi_drive.go and internal/cli/axi_query.go implement the core commands: run, respond, status, logs, and abort.
• Use the --yes flag with axi run to enable fully automated gate approval and CI-ready detection.
• All commands output structured TOON format on stdout, suitable for parsing with jq or similar tools.
• Exit codes are deterministic: 0 for success, 1 for failure, with explicit error fields in the JSON output.
• The IPC architecture in internal/ipc/ ensures reliable communication between the CLI and the background daemon.

Frequently Asked Questions

How do I enable fully non-interactive mode in axi?

Pass the --yes flag to axi run. According to the source code in internal/cli/axi_drive.go, this flag triggers gateResolution logic within driveRun that automatically approves actionable findings and gates without prompting, looping until the run reaches a CI-ready state or termination.

What is the TOON format and how do I parse it?

TOON is a JSON-like structured format that axi emits on stdout for all operations. You can parse it using standard JSON tools like jq. For example, no-mistakes axi status | jq -r '.outcome' extracts the run status, while no-mistakes axi logs --step test streams step-specific output in the same format.

Can I integrate axi with external policy engines?

Yes. Instead of using --yes, invoke axi run without auto-approval to stop at the first awaiting gate, then parse the TOON output to extract gate details. Use axi respond --action <choice> --step <name> to submit decisions from your policy engine, as implemented in newAxiRespondCmd within internal/cli/axi_drive.go.

How does axi handle concurrent runs and idempotency?

The runAxiRun function checks for existing runs matching the current branch and HEAD, re-attaching rather than creating duplicates. Read operations like axi status and axi logs (in axi_query.go) are side-effect-free, while axi abort provides explicit cancellation through MethodCancelRun RPC calls when you need to terminate specific run IDs.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}