Configuration | Ancher
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:
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,neutralfor a reaction — the API ignoresnull) —ancher notes update <id> --clear-reaction. - Short forms cover the busiest flags:
-q/--query,-d/--body,-f/--file,-c/--conversation, plus the globals-h/--helpand-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:
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;
0means it worked. - Discover the surface at runtime via
ancher helpandancher 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
apifor anything the typed commands don’t cover.