@ancher-ai/cli

The command line for Ancher — your personal knowledge base and research assistant. Save anything, find it by meaning rather than keyword, and put an agent to work on it, without leaving your terminal.

npm install -g @ancher-ai/cli
ancher login
ancher chat "what did I save about vector databases?"

Every command prints JSON, authenticates from an environment variable, and rejects an unknown flag before a request leaves your machine — so one interface serves a person at a prompt, a CI job, and an AI agent equally well.

Requires Node 24+.

Authentication

Two modes. The CLI uses the API key when ANCHER_API_TOKEN is set, and otherwise the OAuth2 session saved by ancher login.

Interactive — a human at a terminal:

ancher login    # Authorization Code + PKCE, in your browser
ancher whoami   # the authenticated user
ancher logout   # clear the saved session

The session is written to credentials.json under $ANCHER_CONFIG_DIR, falling back to $XDG_CONFIG_HOME/ancher and then ~/.config/ancher.

Non-interactive — CI, scripts, agents:

export ANCHER_API_TOKEN=sk_your_key_here
ancher whoami

Mint a key from an already-authenticated session:

ancher api-keys create "ci" --expires-in-days 90

Talk to the agent

The reply streams as it is generated.

ancher chat "summarize my recent notes"
ancher chat "and the one about Postgres?" --conversation <id>
ancher chat "plan my reading week" --verbose

--conversation continues an existing thread; --verbose also surfaces the agent's thinking and tool calls. Conversations are first-class objects:

ancher conversations list --limit 5
ancher conversations get <id>

Your knowledge base

Capture from text, a URL, a file, or a conversation:

ancher notes create-text "Kafka rebalances stall consumers for about 3s"
ancher notes create-url "https://example.com/article" --comment "great read"
ancher files upload --file ./diagram.png

Search by meaning rather than keyword — this is retrieval-augmented, so it finds the note you half-remember:

ancher retrieval notes "vector databases"
ancher retrieval chunks "how does presigned upload work"

Organize:

ancher notes list --limit 10 --order-by -updated_at
ancher notes update <id> --title "New title" --public --reaction like
ancher collections create "Reading list" --color blue
ancher collections add-note <id> <noteId>
ancher tags create "urgent" --color red
ancher notes set-tags <id> <tagId> <tagId>

Read a note's body as plain text instead of a JSON envelope:

ancher notes content <id> > note.md

Call any endpoint

The typed commands are sugar over a single authenticated transport, and api exposes it directly — anything the Ancher API can do, the CLI can do:

ancher api GET "notes/?limit=5"
ancher api POST notes/text --body '{"text":"hello"}'
ancher api PATCH notes/{id} --body @patch.json

Reach for it when you need a field the typed commands don't expose yet, or when the payload already exists on disk — --body @file reads it from there.

Output

Stream	Contents
stdout	Pretty-printed JSON: the response, and nothing else. Pipe it to jq.
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.

Two commands return raw bytes on purpose, because that is the point of them: notes content prints the note body, and chat streams prose.

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.
• 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 global -h and -v.
• 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

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.

Command reference

The CLI documents itself: ancher help lists every command, and ancher help <resource> prints one resource's actions with their exact flags.

Group	Resources
Knowledge base	notes collections artifacts tags files
Agent & AI	conversations messages retrieval image-prompt
Inbox & discovery	pins notifications suggestions recommendations
Account	sessions users api-keys connections devices billing

Most resources share the same verbs — list (with --limit, --cursor, --order-by), get <id>, create <primary> [--flags], update <id> [--flags], and delete <id>. A request body's one primary field is a positional argument; every other field is a named flag.

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.
• Parse stdout as JSON. Diagnostics never contaminate it.
• 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, @ancher-ai/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.

Links

• ancher.ai — the product
• @ancher-ai/agent-skills — Ancher skills and MCP setup for coding agents
• Issues — bugs and feature requests

License

Apache-2.0