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.
Nullable fields clear with --clear-<flag>, which sends 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.

If your agent is Claude Code, Codex, or Cursor, Agent Skills installs ready-made Ancher skills plus the hosted MCP server in one step — the agent gets both the know-how and the tools, without shelling out to this CLI.