Caute

The command line

Save to Caute and search it from the terminal: pages by their address, files of any kind, and anything you pipe in. By Axionary Labs, MIT licensed.

npx @caute/cli login
npx @caute/cli save https://example.com/article

Or install it once: npm install -g @caute/cli, then use caute. Node.js 20 or newer is needed.

Sign in

caute login

Caute opens in your browser, where you choose which spaces the command line can use. It can save, write a note on what it saves, and read and search what you've caught in those spaces. Tags it sends arrive as suggestions you confirm in Caute. The sign-in is kept in ~/.config/caute/credentials.json (or $XDG_CONFIG_HOME/caute), readable only by you. caute logout signs this computer out; so does disconnecting "Caute command line" in Caute's Settings, Apps and tokens.

For scripts, set CAUTE_TOKEN to a personal token from Settings, Apps and tokens instead. Give it only what the script needs: a token that can only save (items:write) can save, and nothing else.

Save

caute save https://example.com/article            # a page
caute save report.pdf                             # a file, any size
echo "an idea worth keeping" | caute save -       # whatever you pipe in
caute save notes.md --tag reading/later --tag work --note "For Thursday" --space Research --title "Notes"

Saving the same thing twice says Already saved and makes nothing new. If the connection drops, the command tries again with the same request, so it never saves twice.

Search and open

caute search kelp forests
caute search "lease renewal" --limit 5
caute open 0190f3a2-7c1d-7e4b-9a10-3f2e1d0c9b8a    # in your browser

Add --json to save or search for Caute's answer as JSON.

Gather context for a task

caute gather draft the background section on kelp carbon
caute gather "what did I save about pricing" --budget 1000 --marked

One call returns the best passages for the task within a token budget, grouped by card with its link, its confirmed properties and where each passage sits, your own highlights flagged and put first. Paste the output into a prompt, or --json it into a script. Nothing in it is a model's words: it is quoted from your library and labelled as such.

Recall what your assistants remember

caute recall the Atlas project
caute recall "how I like reports written" --assistant claude

What your assistants remembered about you on a topic (ADR 0160): each memory with the assistant that wrote it, and the card it was learned from. Put it at the top of a prompt so a new assistant starts where the others left off. --assistant keeps to one of them.

Keep a folder in step

caute login --sync
caute sync ~/"Caute Library"            # once
caute sync ~/"Caute Library" --watch    # and keep following changes until Ctrl-C

Use a new or empty folder: caute sync won't write into one that holds other files. (On a Mac, folder names ignore case, so ~/Caute is the same folder as ~/caute.)

Your library as a folder, laid out in Caute's card format, so it opens in Obsidian or any Markdown editor and anything that reads an export reads it.

  • notes/ holds your notes as Markdown, both ways: edit one and the next sync saves it in Caute; write a new .md file and it becomes a note. Links to cards point at files in the folder, and go back to card links when saved.
  • If a note changed in Caute and here, the two are merged the way the web app and iPhone merge. When they can't be, your text stays in the file and is saved, and Caute's is put beside it as <name>.conflict.md.
  • items/<id>/ holds everything else you saved, read-only: item.json (title, text, summary) and the original.
  • Deleting a file deletes nothing in Caute: the next sync puts it back. Delete things in Caute.
  • With --watch, a note you save here reaches Caute within seconds, and changes in Caute arrive within a minute. --refresh fetches every card again, and names any card file that was changed in the folder before putting it back: a card's files are what was caught, and changing one changes nothing in Caute.
  • --agents adds a section to the folder's README.md telling a coding agent how to use it: read items/, write new notes with #agent/<its name> in them, never change a card's files. See Coding agents.

Check a folder against what was caught

caute verify ~/"Caute Library"    # or an unzipped export

Each item.json carries the record of its catch: a fingerprint (SHA-256) of the original as it was caught. caute verify takes each original's fingerprint again and names any file that has changed since it was caught, any card whose original is missing, and how many were caught before records were kept. It exits with 1 if anything differs, so a script can check a folder.

Syncing needs permission to edit your notes, which caute login --sync asks for (a token needs items:read, notes:write and notes:edit).

Exit status

0 when it worked, 1 when Caute or the network said no (the reason is on stderr), 2 when the command was used wrongly.

Building your own

Build a capture surface explains everything this does: tokens and scopes, saving, uploads, retrying safely and handling Caute's answers. This package is its worked example.