# Commands

Talk to the agent, capture and search your knowledge base, and call any endpoint.

## Talk to the agent

The reply streams as it is generated.

```bash
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:

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

## Your knowledge base

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

```bash
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
```

Uploading stores the file and prints it; it does not create a note. Capture it into the knowledge base with the id from that response:

```bash
ancher notes create-file <fileId> --comment "architecture sketch"
```

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

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

Organize:

```bash
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:

```bash
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:

```bash
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.

## 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.