# How to Debug a Failed no-mistakes Pipeline Run Using the axi CLI

> Debug failed no-mistakes pipeline runs using the axi CLI. Quickly find failing steps with `axi status` and view logs with `axi logs` for efficient troubleshooting.

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

---

**Use `no-mistakes axi status` to identify the failing step and `no-mistakes axi logs --step <step>` to view detailed error output, then either resolve the issue with `axi respond` or terminate the run with `axi abort`.**

The `no-mistakes` automation framework provides a command-line interface called **axi** for managing pipeline runs. When a pipeline fails or pauses at a review gate, the axi CLI in the `kunchenguid/no-mistakes` repository offers direct access to execution state, step logs, and control signals without requiring manual database manipulation.

## Understanding the axi CLI Architecture

The axi CLI is implemented as a thin wrapper around the daemon’s RPC interface. Commands are dispatched from [`internal/cli/axi.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/cli/axi.go), while specialized sub-packages handle specific operations:

- **[`internal/cli/axi_render.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/cli/axi_render.go)** – Formats the TOON (JSON-like) representation for status output
- **[`internal/cli/axi_query.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/cli/axi_query.go)** – Queries the daemon for run metadata and step logs via `ReadLogsForStep`
- **[`internal/cli/axi_drive.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/cli/axi_drive.go)** – Processes gate responses and updates the database through `db.SetRunAwaitingAgent`

All run state persists in an SQLite database located at `$NM_HOME/state.db`, specifically in the `run_logs` table and the `awaiting_agent_since` column defined in [`internal/db/run.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/db/run.go).

## Checking Active Run Status

Start debugging by verifying whether an active run exists and identifying its current state.

```bash
no-mistakes axi

```

The home view displays the current branch, any active run ID, and the next suggested action. If a run is paused, the output includes an `awaiting_agent` marker indicating the run is parked at a gate.

For detailed inspection, use:

```bash
no-mistakes axi status

```

This outputs a TOON representation containing a `steps` map where each step includes a `status` field (`pending`, `running`, `awaiting_approval`, `failed`) and an optional `error` string. The `awaiting_agent` field (set in [`internal/pipeline/executor.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/pipeline/executor.go) at line 377) displays the duration the run has been parked, cleared automatically once a response is processed.

```json
{
  "id": "8f3c2a1",
  "branch": "feature/fix",
  "status": "awaiting_approval",
  "awaiting_agent": "parked 2m15s",
  "steps": {
    "review": { "status": "awaiting_approval" },
    "test": { "status": "pending" }
  }
}

```

## Inspecting Step Logs

When a step reports an error, retrieve the full output without re-running the pipeline:

```bash
no-mistakes axi logs --step review --full
no-mistakes axi logs --step test --full

```

The log collector writes entries to the SQLite `run_logs` table (managed in [`internal/db/run_log.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/db/run_log.go)). The CLI retrieves these via `ReadLogsForStep` in [`internal/cli/axi_query.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/cli/axi_query.go), streaming the raw output directly to your terminal. This is the fastest method to diagnose why a specific step failed without executing the entire pipeline again.

## Responding to Paused Gates

If `axi status` shows `awaiting_approval`, the run is parked at a review gate awaiting manual intervention.

**Approve the current gate:**

```bash
no-mistakes axi respond --action approve

```

**Fix specific findings with instructions:**

```bash
no-mistakes axi respond --action fix --findings r1,r2 --instructions "apply the suggested patch"

```

The driver ([`internal/cli/axi_drive.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/cli/axi_drive.go)) validates arguments, writes the response into the run’s database, and clears the `awaiting_agent_since` field. The executor ([`internal/pipeline/executor.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/pipeline/executor.go)) then resumes processing the next step. The handshake logic is verified in [`internal/e2e/executor_approval_test.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/e2e/executor_approval_test.go).

## Aborting Stuck Runs

Terminate a failed or unwanted run using the abort command:

```bash
no-mistakes axi abort               # Abort current branch run

no-mistakes axi abort --run <id>    # Abort specific run by ID

```

Internally, [`internal/cli/axi.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/cli/axi.go) calls the daemon’s `ipc.MethodCancelRun`, which invokes `RunManager.HandleCancel`. The abort path is idempotent: if the run does not exist, the command exits cleanly. This behavior is confirmed in `TestAbortByRunIDReapsRunFromOutsideWorktree`, allowing you to cancel runs from anywhere, even outside the worktree.

## Common Failure Scenarios and Diagnostic Patterns

| Symptom | Likely Cause | Diagnostic Command |
|---------|--------------|-------------------|
| **Run stops at gate** | Review step awaiting manual approval | `axi status` shows `awaiting_agent` flag |
| **Force-push rejected** | Remote branch advanced since run start | Check `error` field in `push` step; see [`internal/pipeline/steps/forcepush.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/pipeline/steps/forcepush.go) |
| **Permission denied in logs** | Daemon lacks proper `$NM_HOME` access | Verify `echo $NM_HOME` and daemon status |
| **Abort has no effect** | No active run on current branch | `axi` home view reports "no active run" |

## Summary

- Use **`no-mistakes axi status`** to view the TOON representation and identify `awaiting_agent` states
- Query specific step failures with **`no-mistakes axi logs --step <name> --full`**, which reads from the SQLite `run_logs` table via [`internal/cli/axi_query.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/cli/axi_query.go)
- Resume gated runs using **`no-mistakes axi respond`**; the driver updates `awaiting_agent_since` in [`internal/cli/axi_drive.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/cli/axi_drive.go)
- Terminate runs with **`no-mistakes axi abort`**, which calls `ipc.MethodCancelRun` and `RunManager.HandleCancel`
- Check **`$NM_HOME/state.db`** directly only when CLI introspection is insufficient; most debugging completes within the axi interface

## Frequently Asked Questions

### How do I check if a no-mistakes pipeline run is currently waiting for approval?

Run `no-mistakes axi status` and examine the `awaiting_agent` field. If present, the run is parked at a gate and the executor in [`internal/pipeline/executor.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/pipeline/executor.go) has set the `awaiting_agent_since` timestamp. The status will also show `status: awaiting_approval` for the specific step that triggered the pause.

### Where are the pipeline logs stored when using the axi CLI?

Logs are stored in an SQLite database at `$NM_HOME/state.db` in the `run_logs` table. The `axi logs` command retrieves these entries through `ReadLogsForStep` in [`internal/cli/axi_query.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/cli/axi_query.go), avoiding the need to interact with the database file directly.

### Can I abort a no-mistakes pipeline run from outside the repository directory?

Yes. Use `no-mistakes axi abort --run <id>` with the specific run identifier. According to the source code in [`internal/cli/axi.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/cli/axi.go), this bypasses the worktree check and calls the daemon’s cancellation directly via `ipc.MethodCancelRun`, allowing you to reap runs from any location.

### Why does my `axi logs` command return "permission denied"?

This error typically indicates the daemon process lacks read permissions on `$NM_HOME/state.db` or the environment variable is misconfigured. Verify that `NM_HOME` points to the correct state directory and ensure the daemon is running with `no-mistakes daemon status` before attempting to query logs.