# Configuration

Flag rules, output streams, environment variables, and driving the CLI from an agent.

## Flags

Flags are validated before anything is sent. A flag a command doesn’t declare fails immediately and names itself, so a typo can never reach the API as silently dropped input:

```bash
ancher notes list --limitt 2      # error: Unknown flag --limitt
ancher notes list --limit abc     # error: --limit must be a number (got "abc")
```

- Values attach inline or as the next token — `--limit=5`, `--limit 5`.
- Booleans are bare and negate with `--no-` — `--public`, `--no-public`.
- Clearable fields clear with `--clear-<flag>`, which sends the field’s own empty value (`''` for a description, `neutral` for a reaction — the API ignores `null`) — `ancher notes update <id> --clear-reaction`.
- Short forms cover the busiest flags: `-q`/`--query`, `-d`/`--body`, `-f`/`--file`, `-c`/`--conversation`, plus the globals `-h`/`--help` and `-v`/`--version`.
- A bare `--` ends option parsing, for free text that starts with a dash — `ancher notes create-text -- "--text that starts with dashes"`.

Secret-bearing flags accept a `--<flag>-stdin` variant that reads one line from stdin, keeping the value out of argv, shell history, and `ps`. Several in one command read successive lines:

```bash
printf '%s\n%s\n' "$OLD_PASSWORD" "$NEW_PASSWORD" |
  ancher users change-password --current-password-stdin --new-password-stdin
```

## Output

| Stream  | Contents                                      |
| ------- | --------------------------------------------- |
| stdout  | The response, and nothing else.              |
| stderr  | Progress, warnings, and errors.               |

Exit code `0` on success, `1` on any failure. Errors are actionable rather than raw — an HTTP 401 tells you to run `ancher login`.

### What stdout contains

Anything that returns a record or a page prints pretty-printed JSON — pipe it to `jq`. The rest is deliberate:

| Kind of command                          | stdout                         | Examples                             |
| ---------------------------------------- | ------------------------------ | ------------------------------------ |
| Returns a record or page                 | JSON                           | `notes list`, `notes get`, `notes update`, `whoami` |
| Only performs an action                  | a one-line confirmation        | `Deleted.`, `Revoked.`, `Removed.`, `Unpinned.`, `Disconnected.`, `Logged out.` |
| Exists to emit content                   | the raw content                | `notes content`, `artifacts content` |
| Streams                                  | prose, as generated           | `chat`                               |
| Passes through                           | whatever the endpoint returned | `api`                                |

**If you are scripting this, do not branch on the command name.** The list of action commands grows, and a confirmation line is a _success_, not an error. Use the exit code to decide whether the call worked, and parse stdout as JSON only when you asked for a record.

## Environment variables

| Variable                      | Purpose                                               |
| ----------------------------- | ---------------------------------------------------- |
| `ANCHER_API_TOKEN`           | API key for non-interactive auth. Takes precedence over the saved session.
| `ANCHER_API_BASE_URL`        | Target a non-default API origin. Same as `--base-url`.
| `ANCHER_CONFIG_DIR`          | Where the OAuth2 session is stored. Defaults to `$XDG_CONFIG_HOME/ancher`, then `~/.config/ancher`.

## Driving this from an AI agent

`ancher` is built to be called by a program, not just typed:

- **Authenticate with `ANCHER_API_TOKEN`.** No browser, no prompt, no local state.
- **Read stdout, and trust the exit code.** Diagnostics never contaminate stdout, so whatever lands there is the answer — JSON for anything returning a record, a confirmation line for an action. Do not treat a non-JSON body as a failure; `0` means it worked.
- **Discover the surface at runtime** via `ancher help` and `ancher help <resource>` instead of hardcoding a command list.
- **Trust the flag validator.** A wrong guess fails loudly and names the flag, rather than sending a request that quietly omits your data.
- **Fall back to `api`** for anything the typed commands don’t cover.