Agentic Hoots — The HootBook CLI

01 / Understand the tool

An agent can work with your notes

CLI means command-line interface: you type a command in Terminal instead of choosing a button. An AI agent is an assistant that can carry out a task using tools. If yours can run Terminal commands, it can use hootbook. “Agentic Hoots” describes that work with HootBook; the command you actually type is hootbook.

For example, an agent could find your renewal notes, read the relevant ones, and prepare a follow-up note. The CLI handles finding, reading and saving. Your agent reads the notes it needs and drafts the text.

Commands go through the HootBook app running on your Mac. The app reads and changes notes, and a saved change syncs to your other devices in the usual way. The CLI does not open the vault files itself or choose an AI provider.

Frontier in a note: Frontier brings the AI you choose into your journal as your personal assistant. Start with //. The response appears in a Hoot Page, where you can reply and choose Include.
Terminal command: You or an agent run commands in Terminal. Once writes are enabled, a write command applies its change directly. There is no Hoot Page or Include step.

02 / Get connected

Install it, then check it

The CLI is available on Mac. Open HootBook, then go to Settings › Setup assistant › Extras and choose Install beside Command-line tool. It installs a small launcher at ~/.local/bin/hootbook; the commands themselves are part of the app.

Open Terminal and run these checks first:

Check the version, connection and background status

hootbook version --json
hootbook doctor --json
hootbook anchor status --json

version checks that the launcher and running app match. doctor checks installation, connection, note availability and whether writes are allowed. Fix any issues it reports before asking an agent to change notes.

If Terminal says “command not found,” use ~/.local/bin/hootbook in place of hootbook. You can later add ~/.local/bin to your shell’s PATH, the list of folders it searches for commands. If you move HootBook, install the launcher again from that copy of the app.

Note commands need HootBook running. You can simply keep the app open. Optional Anchor keeps it available after its window closes; anchor status only checks it and does not turn it on. Version, health and installation commands also work while the app is stopped.

03 / Start with reading

Find a note and read it

These commands read information without changing notes. This search looks for “renewal” and returns up to five matches:

Search for notes

hootbook find --text renewal --limit 5 --json

--json prints the result in JSON, a format scripts and agents can read. Copy the matching note’s documentId. Use this value, not the note’s title. Replace the placeholder below with that exact value and keep the quotes.

Read the note you found

note_id='PASTE_DOCUMENT_ID_HERE'
hootbook read "$note_id" --json

The result includes the note’s text, tags and contentHash, a value that identifies the version you read. Save that hash if you plan to edit the note later. For just the writing, use:

Read only the body

hootbook read "$note_id" --body

You can also narrow a search to an existing tag or recent changes:

Use an existing tag and a date range

hootbook tags --counts
hootbook find --tag work --modified-after 30d --json

Replace work with a tag your notes already use. 30d means the past 30 days. A tag search includes its child tags; work also includes work/renewals.

04 / Review a change

Preview before you write

Writes are off by default on each Mac. Run hootbook status to see the current setting. It prints the command for enabling writes on that Mac if you decide to allow them. Keep that choice separate from installing the CLI or checking its health.

In the current version, even a preview using --dry-run requires writes to be enabled. The preview itself changes nothing. Every write also needs --as, a name recorded with the change.

Once you have deliberately enabled writes, this example previews a new note. It supplies sample text through the pipe, |; --body - tells HootBook to read that text.

Preview a new note without saving it

printf '%s\n' 'Follow up on the renewal date.' |
  hootbook create --title 'Renewal follow-up' \
  --body - --as example-agent --dry-run --json

Read the preview. When you want to save the note, run the same command without --dry-run:

Create the note after reviewing the preview

printf '%s\n' 'Follow up on the renewal date.' |
  hootbook create --title 'Renewal follow-up' \
  --body - --as example-agent --json

This saves a new note immediately. The result identifies the note and its new content hash. Running the create command again can create another note, so check the result before repeating it.

05 / Protect recent edits

Change the version you reviewed

To edit an existing note, first read it with --json. Use the documentId and contentHash from that same result. Put the complete replacement body in a plain text file named draft.md in Terminal’s current folder.

Preview a replacement body for the version you read

expected_hash='PASTE_CONTENT_HASH_HERE'
hootbook edit "$note_id" --body draft.md \
  --expect-hash "$expected_hash" --as example-agent \
  --dry-run --json

edit replaces the whole body, rather than adding text at the end. It keeps the title, tags and other note details, apart from the updated modification time and agent name. As with creating a note, remove --dry-run only when you want to apply the reviewed change.

--expect-hash refuses the edit if the note has changed since you read it. If that happens, read the latest note, update your draft to keep the changes you want, and preview again with the new hash. Keep the check in place when you apply the edit.

The same hash check is available for tag. Use it when an agent changes an existing note’s tags. Existing tag spellings are reused; a new tag name is refused unless you explicitly use --force.

06 / Set the task

Give your agent a clear job

Tell the agent which notes it may read, what it should produce, and whether it may save anything. For a first task, you could say:

Use the HootBook CLI to find my renewal notes. Show me the matching titles and IDs first. Read only the notes I select. Draft one follow-up note and show me its text. Keep the current write and Anchor settings. Do not save changes until I ask.

A useful sequence is: check the CLI, find a small set of notes, read the relevant ones, prepare the change, preview it, then apply it within the permission you gave. For edits, keep the hash from the version the agent read.

The CLI connection stays on your Mac. If your agent uses an online AI service, the note text it reads may be sent to that service. Choose the agent and the notes with that in mind; the CLI does not control the agent’s later use of the text.

--as example-agent records example-agent in the note’s agent field. Whoever runs the command chooses that name, so it does not verify who made the change. HootBook records the write as a change from this Mac.

07 / Keep going

When a command needs attention

App not running: Open HootBook and try again. If you want background availability, review Anchor in the app; checking the CLI does not enable it.
Version mismatch: Run Install from the HootBook copy you intend to use, then check version --json and doctor --json again.
No matches: A search can work and find nothing. Try a broader term or check the tag spelling. Exit code 2 means no matches; 0 means success and 1 means an error.
Writes are off: You can still read notes. Run hootbook status to check the setting and see the command for enabling writes on this Mac. The setting helps prevent accidental changes. Other software running under your Mac account can change it too.
More commands: hootbook help lists the commands and flags. backlinks finds notes that link to a note; conflicts lists notes with competing versions. delete removes notes and also supports a dry run.

The note CLI has no calendar commands. Calendar changes use the app’s calendar connection and its review and confirmation controls.