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

# AI agents

> Use the TalkValue CLI from AI coding assistants. Structured JSON output, deterministic exit codes, and 11 bundled skills.

The TalkValue CLI gives AI coding agents a structured data layer for your workspace. Every command emits structured JSON, every failure mode maps to a stable exit code, and the read commands are safe to invoke without side effects. Pair the CLI with the bundled skills and any agent can list, get, update, import, and analyze workspace data without custom tooling.

## Why the CLI is agent-friendly

* **Structured JSON on every command.** Pipe-detection auto-switches to JSON, or pass `--json` explicitly. Errors return a `{ "error": { "message": "..." } }` envelope on stderr. See [Output format](/cli/output-format).
* **Stable exit codes.** `0` success, `2` usage, `3` authentication, `4` not found, `5` forbidden. Branch on the integer, not the prose. See [Exit codes](/cli/exit-codes).
* **Idempotent reads.** Every `list`, `get`, `export`, and analysis call is a pure read. Running it twice produces the same result and never mutates state.
* **Predictable mutation surface.** `update`, `create`, `delete`, `merge`, `attach`, and `import create` are the only write paths, each documented with required flags and explicit confirmation where destructive (`--confirm`).
* **`llms.txt` discovery.** Fetch the [llms.txt index](https://docs.trytalkvalue.com/llms.txt) for a flat list of every docs page, suitable for embedding in an agent's retrieval layer or context window.
* **Skills bundled with the binary.** 11 skill files ship inside the [GitHub repo](https://github.com/talkvalue/cli). Install them all with `npx skills add https://github.com/talkvalue/cli` and the agent can navigate the whole CLI surface without reading every doc page first.

## How an agent uses the CLI

A typical agent loop looks like:

```bash theme={null}
# 1. Discover IDs
talkvalue path event list --json

# 2. Read state
talkvalue path event person list 18 --sort "joinedAt,desc" --page-size 50 --json

# 3. Decide

# 4. Write (with explicit confirmation on destructive paths)
talkvalue path person update 142 --job-title "Director of Marketing"

# 5. Verify
talkvalue path person get 142 --json
```

Each step is a single CLI invocation that returns parseable JSON and a definitive exit code. The agent never needs to scrape terminal output.

<CardGroup cols={2}>
  <Card title="AI agent skills" icon="cubes" href="/cli/agents/skills">
    The 11 bundled `SKILL.md` files (7 command-group wrappers, 1 shared reference, and 3 workflow recipes) installable via `npx skills add`.
  </Card>

  <Card title="Recipes" icon="book" href="/cli/recipes/index">
    Multi-step shell workflows your agent can compose: registrants, CSV import, channel analysis, jq scripting.
  </Card>
</CardGroup>

## Related

* [Authentication](/cli/authentication). How to use `TALKVALUE_TOKEN` for headless agent runs.
* [Global flags](/cli/global-flags). `--json`, `--profile`, `--api-url`, and the rest.
* [Troubleshooting](/cli/troubleshooting). Common failure modes by exit code.
* [llms.txt](https://docs.trytalkvalue.com/llms.txt). Flat index of every docs page.