CLI Command Reference
Understand command syntax, global options, output formats, and the complete Octarine CLI reference.
The Octarine CLI uses the form octarine [global options] <command> [command options]. Every public command is documented in this section with its syntax, behavior, and at least one example.
Choose A Command Area
| Area | Commands |
|---|---|
| Workspaces and search | workspace, search |
| Notes | note create, read, context, targeted edits, tasks, and every other note operation |
| Folders, links, and tasks | folder, link, workspace-wide task and tag |
| Properties and resources | property, metadata, view, note-type, theme |
| Inbox | Capture, promote, snooze, tag, resolve, and diagnose Inbox items |
| Agents and MCP | agent-guide, help --json, mcp |
| Automation and maintenance | Output formats, errors, config, schema, export, capabilities, doctor, completion, update |
Global Options
Global options can appear before or after a subcommand.
| Option | Purpose |
|---|---|
--workspace <name, uuid, or path> | Select a workspace. Also available as OCTARINE_WORKSPACE. |
--app-store <path> | Override the desktop workspace registry. Also available as OCTARINE_APP_STORE. |
--database <path> | Override the shared SQLite database. Also available as OCTARINE_DATABASE. |
--json | Emit one stable JSON envelope. |
--jsonl | Emit one JSON object per result. |
--format <table, plain, json, or jsonl> | Select an output format explicitly. Also available as OCTARINE_FORMAT. |
--fields <a,b,c> | Project selected fields from object or array output. |
--request-id <id> | Echo a caller-provided ID in machine-readable response metadata. |
--quiet | Suppress non-essential output. |
--verbose | Reserved for diagnostic output. Currently has no effect. |
--no-color | Disable ANSI styling. NO_COLOR is also honored. |
--no-progress | Reserved for disabling progress indicators. Currently has no effect. |
--non-interactive | Reject prompts rather than waiting for input. Only update prompts today. |
octarine --workspace "Work Notes" note list
octarine note list --workspace ~/Notes --json
octarine search launch --fields path,line,text --format jsonl--json, --jsonl, and --format are alternative output selectors. Do not combine them.
Without an output option, the CLI uses OCTARINE_FORMAT, then the format setting from octarine config. If none is set, it prints tables in a terminal and tab-separated plain output when piped to another program.
Workspace Paths
Paths such as Projects/Launch.md are relative to the selected workspace. Quote names containing spaces. The CLI rejects traversal and symlink paths that escape the workspace.
octarine --workspace ~/Notes note read "Projects/Launch plan.md"Workspace selection follows this order:
--workspaceOCTARINE_WORKSPACE- The nearest parent containing
.octarine - The default saved with
octarine workspace use - The sole workspace in the desktop app registry
Get Exact Installed Syntax
The installed executable is authoritative when versions differ from these docs.
octarine --version
octarine --help
octarine note --help
octarine note create --help
octarine help note edit --jsonhelp --json describes every command, argument, output envelope, and error code in machine-readable form. See Agents and MCP.
Workspace registration, renaming, removal, and deletion are intentionally not public CLI operations. workspace use only changes the CLI's default workspace. The desktop app owns those registry mutations.