> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentx.wft/llms.txt
> Use this file to discover all available pages before exploring further.

# Output and exit codes

> Read agentx output from a script and act on its exit codes.

## Text output

Without `--json`, every command prints aligned text for you to read. Tables pad their columns, a row that reports a state starts with a glyph (`✓` ok, `!` warning, `✗` failure, `•` information), and a command that changes something confirms it on one line:

```text theme={null}
✓ label is now work laptop
```

Text that comes from somewhere else is cleaned before it is printed: tabs, newlines and other control characters become spaces, so one item stays one row and nothing can drive your terminal. That covers the name and description a source writes for its skills and the directory it keeps each one in, the name of a directory in your library or your client's configuration, the command line an MCP server is declared with, and what agentx relays of what something else said, including the messages a git server sends back when you add a source.

Paths are quoted instead of cleaned, so you can still copy one. A path holding a control character is printed in double quotes with escapes, the way `git status` prints such a path:

```text theme={null}
    nasty  directory  user  "~/.claude/skills/na\033[31msty"
```

Read any value exactly as it was written with `--json`, which escapes it instead of cleaning it.

## Colour

Text output is coloured when it goes to a terminal. Each colour means one thing everywhere: green for ok and enabled, yellow for a warning, a hint and disabled, red for a failure and an error, blue for information, cyan for a key or a flag name, and dim for secondary detail.

Output piped into another program or a file carries no colour, so the text a script reads is the same as before. Control it explicitly with the global `--color` flag:

```sh theme={null}
agentx --color on doctor | less -R
agentx --color off scan
```

Set the `NO_COLOR` environment variable to any value to turn colour off in every terminal. `--json` output is never coloured.

## JSON output

Add `--json` before or after any command to get one JSON object per line on stdout. Every object has a `type` and an integer `schema_version`. The last line is always a `result` with `ok` set to `true` or `false`.

```sh theme={null}
agentx --json version
```

Parse each line on its own. Read the exit code before trusting the output.

## Logs

Logs go to stderr, never to stdout. A line starting `warning:` is something to look at, and one starting `info:` is a note that asks nothing of you, such as a failure warned about earlier that has ended. Add `--verbose` to see debug lines too, such as which agentx home and library the command used. With `--json`, log lines are JSON objects too, and each one's `level` is `warn`, `info` or `debug`. More levels may be added later, so show one you do not know as it is written.

Some warnings put what to do on a second line, indented under the warning. With `--json`, such a warning is still one `log` event, and its `message` holds both lines joined by `; `.

## Errors

A failed command prints `error: ...` and, when there is a fix, `hint: ...` on stderr. With `--json` it emits an `error` event with `code`, `message` and `hint` instead, followed by a `result` with `ok: false`.

## Exit codes

| Exit code | Code | Meaning |
| - | - | - |
| 0 | `ok` | Success. |
| 1 | `usage` | Unknown command, bad flag or missing argument. Run `agentx help`. |
| 2 | `git` | Git is missing or older than 2.40. Install or upgrade git. |
| 3 | `source` | A source is unreachable or authentication failed. |
| 4 | `pending_merge` | A pending merge blocks the action, or `skill update` left one pending because [your edits conflict with the update](/cli/skill#when-your-edits-conflict), or found files of one still to resolve. |
| 5 | `not_found` | The skill, source or configuration does not exist. |
| 6 | `refused` | A collision or an unmet precondition. |
| 7 | `locked` | Another agentx command is running. Retry when it finishes. |
| 8 | `account_repo` | The account repo is unusable. |
| 9 | `interrupted` | You stopped the run with Ctrl-C, or something sent it a `SIGTERM`. |
| 10 | `internal` | An internal error. The message names the file or command involved. |

## Stop a run

Press Ctrl-C, or send `SIGTERM`, to stop a run. agentx stops the git command it is waiting on, prints `error: interrupted` with a hint, and exits `9`:

```text theme={null}
error: interrupted
hint: run the command again; 'agentx doctor' names anything the stop left behind
```

A change that had already started is finished before the run stops, and one that had not started leaves nothing behind. The exception is a stop sent to the whole process group agentx runs in, most commonly Ctrl-C in a terminal. Such a stop also reaches the git command agentx is running, so a change caught while it was being written to the account repo can stop part way. That is safe: agentx writes down what it is about to do before it does it, the next agentx command finishes or rolls it back, and `agentx doctor` tells you one is waiting. Run the command again when you are ready.

Press Ctrl-C a second time to kill the run outright. That is safe for the same reason: the next agentx command finishes or rolls back what the killed run left, and `agentx doctor` shows whether anything is waiting.

A run that had already finished everything you asked for exits `0`: the signal arrived too late to change the outcome, and agentx reports what it did.

Run agentx in the background from a script and Ctrl-C in that terminal leaves it alone, exactly as it leaves every other background job alone.

## Directories

| Variable | Default | Use |
| - | - | - |
| `AGENTX_HOME` | `~/.agentx` | Where agentx keeps its own state. |
| `AGENTX_LIBRARY` | `~/.agents/skills` | The library of skills agentx manages. |

Set either to move that directory. `agentx` reads `HOME` and `XDG_CONFIG_HOME` to find your agent clients.


## Related topics

- [agentx doctor](/cli/doctor.md)
- [agentx scan](/cli/scan.md)
- [agentx](/index.md)
- [agentx skill](/cli/skill.md)
- [agentx source](/cli/source.md)