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

> Automate Agent eXperience with the axi CLI. Use flags and structured TOON data for seamless CI/CD workflows with commands like axi run --yes.

- Repository: [Kun Chen/no-mistakes](https://github.com/kunchenguid/no-mistakes)
- Tags: how-to-guide
- Published: 2026-06-27

---

**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`](https://github.com/kunchenguid/no-mistakes/blob/main/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`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/cli/axi_drive.go) via `newAxiRunCmd`, this command starts or attaches to pipeline runs.
- **`axi respond`** – Also in [`axi_drive.go`](https://github.com/kunchenguid/no-mistakes/blob/main/axi_drive.go), handles gate approvals through `newAxiRespondCmd`.
- **`axi status`** – Defined in [`internal/cli/axi_query.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/cli/axi_query.go) via `newAxiStatusCmd` for read-only state inspection.
- **`axi logs`** – Implemented in [`axi_query.go`](https://github.com/kunchenguid/no-mistakes/blob/main/axi_query.go) through `newAxiLogsCmd` for streaming step logs.
- **`axi abort`** – Located in [`axi_drive.go`](https://github.com/kunchenguid/no-mistakes/blob/main/axi_drive.go) via `newAxiAbortCmd` for cancellation operations.

### Daemon IPC Communication

All commands rely on `openAxiEnv` (in [`axi.go`](https://github.com/kunchenguid/no-mistakes/blob/main/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`](https://github.com/kunchenguid/no-mistakes/blob/main/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.

```bash
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`](https://github.com/kunchenguid/no-mistakes/blob/main/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.

```bash
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`](https://github.com/kunchenguid/no-mistakes/blob/main/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.

```bash
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`](https://github.com/kunchenguid/no-mistakes/blob/main/axi_drive.go) issues `MethodCancelRun` RPC calls to terminate runaway processes.

```bash
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.

```bash
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`](https://github.com/kunchenguid/no-mistakes/blob/main/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`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/cli/axi_drive.go) and [`internal/cli/axi_query.go`](https://github.com/kunchenguid/no-mistakes/blob/main/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`](https://github.com/kunchenguid/no-mistakes/blob/main/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`](https://github.com/kunchenguid/no-mistakes/blob/main/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`](https://github.com/kunchenguid/no-mistakes/blob/main/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.