CLI for agents

We recommend the CLI for agents with shell access. Start with the skill installation prompt to teach your agent the commands and ask it to remember to use Loofah through loof for persistent notes and saved knowledge. If needed, install the CLI too.

Pass the global --json flag when software consumes CLI output. A successful response contains schema_version, command, data, and, for paginated commands, pagination.

Find the session first

loof --json sessions list --query "weekly planning" --limit 10
loof --json sessions get SESSION_ID

List filtering matches titles and IDs without regard to case. For full-text search across notes, summaries, and transcripts, use sessions search. If several sessions match the user’s request, ask which one they mean.

Read only what you need

loof --json sessions note SESSION_ID --kind note
loof --json sessions note SESSION_ID --kind summary

Use sessions get when you also need metadata or action items.

Transcripts

loof --json sessions transcript SESSION_ID

This returns the complete speaker-labeled transcript in one response. Transcripts can be large, so do not request one unless the task needs it.

Check the setup

loof --json doctor

Vault commands automatically initialize a missing or incompatible cache; progress streams on stderr. Use loof --json init for explicit setup or repair.

The report includes cache readiness, the CLI version, a ready flag, the resolved vault path, path health, and the number of sessions. It exits with status 1 when ready is false, while still writing the report to standard output.

For a non-default vault, use --vault-path DIR or LOOFAH_VAULT_PATH.

Store agent work

loof --json sessions new --title "Weekly planning" --note notes.md --author claude-code
loof --json sessions new --title "Research: payment providers" --note research.md --tag research --author claude-code --skill research-assistant
loof --json sessions note SESSION_ID --append notes.md
loof --json sessions attach SESSION_ID source-deck.pdf
loof --json import recording.m4a --transcribe --author claude-code
loof --json transcribe SESSION_ID

sessions new creates a session and prints its ID; --note seeds the note body from a file or stdin (-). The session can stand alone as a note, with no recording or transcript. This lets an agent store a research brief, extracted deck insights, project context, or other useful output from any source it is authorized to access. The agent performs the source integration and supplies Markdown; loof provides the stable write path into the vault.

sessions note --set replaces the note body and --append extends it; both also accept - for stdin. sessions attach stores a source artifact beside the note. import creates a session from an audio file, and --transcribe chains on-device transcription. transcribe replaces the session’s existing transcript, so run it only when the user wants that.

Always pass --author <your-agent-name> when creating a session (sessions new, import). It marks the note as not written by the vault owner, and the app surfaces that. Use one stable name, such as claude-code. When a reusable skill produced the result, also pass --skill <skill-name>. Write your own notes as new sessions; when editing an existing note, never change its authorship.

Only store content when the user asks. Respect the permissions and privacy boundary of the source tool, and do not send vault content elsewhere merely to re-import it.

Note

On-device transcription requires macOS on Apple Silicon and the on-device Soniqo model configured in the desktop app. The CLI never downloads models, so open the desktop app once to download it.

Remove a session when asked

Verify the redundant session’s exact ID with sessions get before deleting it:

loof --json sessions delete SESSION_ID

This moves the complete session to recoverable vault trash. There is no prompt or confirmation flag, so only invoke it after the user authorizes removal. Keep the response’s original path, trash_path, and deleted_at for recovery. A missing or repeated deletion returns not_found (exit 2). See deletion and manual recovery for failure behavior and recovery steps to give the user. MCP remains read-only.

Export only when asked

loof sessions export SESSION_ID --format markdown --output session.md
loof sessions export SESSION_ID --format json --output session.json
loof sessions export SESSION_ID --format txt --include transcript
loof sessions export SESSION_ID --format pdf --include note,summary,transcript --output session.pdf

PDF/TXT/Org default to note and summary; --include selects specific content. Read the export behavior and JSON compatibility policy before combining --json with file output. Export refuses to replace an existing file. Pass --force only when the user has approved overwriting that exact path.

See the CLI reference for the full command contract.