CLI for agents

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

loofah --json sessions list --query "weekly planning" --limit 10
loofah --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

loofah --json sessions note SESSION_ID --kind note
loofah --json sessions note SESSION_ID --kind summary

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

Transcripts

loofah --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

loofah --json doctor

The report includes 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

loofah --json sessions new --title "Weekly planning" --note notes.md --author claude-code
loofah --json sessions new --title "Research: payment providers" --note research.md --tag research --author claude-code --skill research-assistant
loofah --json sessions note SESSION_ID --append notes.md
loofah --json sessions attach SESSION_ID source-deck.pdf
loofah --json import recording.m4a --transcribe --author claude-code
loofah --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; loofah 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.

Export only when asked

loofah sessions export SESSION_ID --format markdown --output session.md
loofah sessions export SESSION_ID --format json --output session.json

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.