Automation and Maintenance

Machine-Readable Output

All commands accept the global output options described in the command reference.

When no output option is given, the CLI uses OCTARINE_FORMAT, then the format setting from octarine config. Otherwise it prints tables in a terminal and plain output when piped.

Plain

plain prints tab-separated text with no borders or quoting, which suits cut, awk, and grep. Lists print one row per line; objects print one key<TAB>value line per field.

octarine note list --sort modified --limit 2 | cut -f5
octarine config set format plain

Projects/Launch.md
Home.md

--json emits a stable envelope with schemaVersion, ok, data, and meta. meta always includes truncated, plus nextCursor for a search with more results and requestId when you pass --request-id. Errors use the same envelope with an error object; see Errors.

octarine note list --json
octarine note read Projects/Launch.md --json --request-id agent-42

# `note list --json`
{"schemaVersion":1,"ok":true,"data":["Daily/2026-10-15.md","Projects/Launch.md"],"meta":{"truncated":false}}

# `note read … --json --request-id agent-42`
{"schemaVersion":1,"ok":true,"data":{"path":"Projects/Launch.md","content":"# Launch\n","revision":"sha256:9be317c2…"},"meta":{"requestId":"agent-42","truncated":false}}

JSONL

--jsonl or --format jsonl emits one result per line for streaming consumers.

octarine search launch --jsonl
octarine task list --todo --format jsonl

# Search JSONL
{"line":1,"path":"Projects/Launch.md","text":"# Launch"}

# Task JSONL
{"checked":false,"id":4,"line":4,"path":"Projects/Launch.md","text":"Publish release notes"}

Field projection and bounds

Select output fields and bound search output before handing it to an agent.

octarine search launch \
  --fields path,line,text \
  --limit 10 \
  --max-output-bytes 12000 \
  --json

{"schemaVersion":1,"ok":true,"data":[{"path":"Projects/Launch.md","line":1,"text":"# Launch"}],"meta":{"truncated":false}}

If the byte limit removes results, JSON metadata reports truncated: true and includes a nextCursor for fetching the rest.

Errors

With --json or --jsonl, failures print an error envelope instead of data:

{"schemaVersion":1,"ok":false,"error":{"code":"REVISION_CONFLICT","message":"revision conflict: current revision is sha256:baa6e604…","retryable":true,"currentRevision":"sha256:baa6e604…","hint":"The note changed since you read it. Re-read it and retry with --revision <currentRevision>."},"meta":{}}

Field	Meaning
`code`	Stable error code from the table below
`message`	Human-readable description
`retryable`	`true` when retrying after re-reading can succeed
`currentRevision`	The note's current revision, on `REVISION_CONFLICT`
`hint`	Suggested next step, when one applies

In table and plain output, the message is printed to standard error as error: <message>. In every format, the process exits with the code for that error.

Code	Exit code	Meaning
`NOT_FOUND`	`3`	Note, folder, section, or resource does not exist
`ALREADY_EXISTS`	`4`	Destination already exists
`REVISION_CONFLICT`	`4`	Note changed since it was read
`AMBIGUOUS_MATCH`	`2`	Edit text or heading matched more than once
`PATCH_FAILED`	`2`	A diff hunk did not match the note
`INVALID_EDIT`	`2`	Edit arguments are invalid
`INVALID_ARGUMENT`	`2`	An option value is invalid
`INVALID_PROPERTY`	`2`	Property value does not match its definition
`PATH_ESCAPE`	`5`	Path leaves the workspace
`WORKSPACE_REQUIRED`	`5`	No workspace selected
`WORKSPACE_INVALID`	`1`	Workspace path is missing or unreadable
`RUNTIME_ERROR`	`1`	Any other failure

octarine help --json returns this table too, so scripts and agents can read it from the installed version.

Exit Codes

Code	Meaning
`0`	Success
`1`	General runtime failure or unreadable workspace
`2`	Invalid input: option value, property value, ambiguous edit, or failed patch
`3`	Resource not found
`4`	Conflict, existing resource, or stale revision
`5`	Workspace selection, permission, or path-safety failure
`7`	Schema, metadata, or corruption failure

`config`

Manage user-level CLI settings stored in cli.toml.

octarine config list
octarine config get <key>
octarine config set <key> <value>
octarine config unset <key>
octarine config path

octarine config list
octarine config set format json
octarine config get format
octarine config unset format

# `config list`
╭──────────────────────────────────────────────────────────────────┬───────────┬────────────╮
│ description                                                      ┆ key       ┆ value      │
╞══════════════════════════════════════════════════════════════════╪═══════════╪════════════╡
│ Default workspace (name, UUID, or path) when no --workspace, …   ┆ workspace ┆ Work Notes │
│ Default output format: table, plain, json, or jsonl (otherwise … ┆ format    ┆ —          │
╰──────────────────────────────────────────────────────────────────┴───────────┴────────────╯

# `config get format`
json

Key	Values
`workspace`	A workspace name, UUID, or path. Also set by `octarine workspace use`.
`format`	`table`, `plain`, `json`, or `jsonl`

config get exits with code 3 when the key is not set. config path prints the settings file location. Set OCTARINE_CONFIG to use a different file, for example in CI or tests. Unknown keys and invalid formats are rejected.

`schema list`

List the persisted contracts understood by this CLI build.

octarine schema list
octarine schema list --json

# Default table output
╭───────────────┬──────────────────────────────────────────╮
│ Field         ┆ Value                                    │
╞═══════════════╪══════════════════════════════════════════╡
│ schemaVersion ┆ 1                                        │
│ schemas       ┆ note, property, view, type, theme, inbox │
╰───────────────┴──────────────────────────────────────────╯

# JSON output
{"schemaVersion":1,"ok":true,"data":{"schemaVersion":1,"schemas":["note","property","view","type","theme","inbox"]},"meta":{"truncated":false}}

Current resource names include note, property, view, type, theme, and inbox.

`schema show`

Describe one supported resource contract.

octarine schema show note
octarine schema show theme --json

# `schema show note`
╭───────────────┬──────────────────╮
│ Field         ┆ Value            │
╞═══════════════╪══════════════════╡
│ format        ┆ markdown-or-json │
│ resource      ┆ note             │
│ schemaVersion ┆ 1                │
│ version       ┆ 1                │
╰───────────────┴──────────────────╯

# `schema show theme --json`
{"schemaVersion":1,"ok":true,"data":{"format":"markdown-or-json","resource":"theme","schemaVersion":1,"version":1},"meta":{"truncated":false}}

An unknown resource exits with a not-found error.

`export`

Export every note, its revision, and .octarine JSON metadata as one JSON document. Without --output, the document is written to standard output.

octarine export --json > workspace-export.json
octarine export --output workspace-export.json

# The redirected `--json` command writes the JSON response envelope,
# including the export document, to the file.
# `--output` prints:
╭──────────┬───────╮
│ Field    ┆ Value │
╞══════════╪═══════╡
│ exported ┆ true  │
╰──────────┴───────╯

--output writes pretty JSON to the requested file and prints a small success response. An export is a data interchange snapshot, not a replacement for backing up the original Markdown workspace.

`capabilities`

List feature identifiers supported by the installed CLI. Agents can use this instead of guessing from a version number.

octarine capabilities
octarine capabilities --json

# Default table output
╭───────────────┬────────────────────────────────────────────────────────╮
│ Field         ┆ Value                                                  │
╞═══════════════╪════════════════════════════════════════════════════════╡
│ capabilities  ┆ app-workspace-discovery, note-crud, …, help-json, mcp │
│ schemaVersion ┆ 1                                                      │
╰───────────────┴────────────────────────────────────────────────────────╯

# JSON output (abridged values, stable field names)
{"schemaVersion":1,"ok":true,"data":{"capabilities":["app-workspace-discovery","note-crud",…,"cli-config","targeted-edits","note-context","link-refactoring","markdown-links","search-cursors","note-sorting","help-json","mcp"],"schemaVersion":1},"meta":{"truncated":false}}

This command does not require a selected workspace. For example, check for targeted-edits before using note edit, or mcp before starting octarine mcp.

`doctor`

Check the selected workspace's structure and metadata.

octarine doctor --workspace ~/Notes
octarine --workspace ~/Notes doctor
octarine --workspace "Work Notes" doctor --json

# Human output
╭────────┬────────────────────────────────────────╮
│ Field  ┆ Value                                  │
╞════════╪════════════════════════════════════════╡
│ path   ┆ /home/alex/Notes                       │
│ report ┆ {"healthy":true,"notes":24,"folders":5,…} │
╰────────┴────────────────────────────────────────╯

# JSON output
{"schemaVersion":1,"ok":true,"data":{"path":"/home/alex/Work Notes","report":{"healthy":true,"notes":24,"folders":5,"metadata":{"properties.json":"valid","schema.json":"valid","themes.json":"valid","types.json":"valid","views.json":"valid"},"warnings":[]}},"meta":{"truncated":false}}

Use workspace doctor <identifier> when selecting the workspace as a positional identifier is more convenient, and inbox doctor for Inbox-specific consistency.

`completion`

Generate completion definitions for Bash, Elvish, Fish, PowerShell, or Zsh.

octarine completion <bash|elvish|fish|powershell|zsh>

octarine completion zsh > ~/.zfunc/_octarine
octarine completion bash > ~/.local/share/bash-completion/completions/octarine
octarine completion fish > ~/.config/fish/completions/octarine.fish
octarine completion powershell > octarine.ps1
octarine completion elvish > octarine.elv

No terminal output; each command writes the generated completion definition to the redirected file.

Load the generated file using your shell's normal completion configuration.

`update`

Check for and install an independently released CLI update.

octarine update --check
octarine update
octarine update --yes --non-interactive

# Possible representative `--check` output when an update is available
╭─────────────────┬──────────────────────╮
│ Field           ┆ Value                │
╞═════════════════╪══════════════════════╡
│ currentVersion  ┆ 0.4.0                │
│ latestVersion   ┆ 0.5.0                │
│ publishedAt     ┆ 2026-09-30T12:00:00Z │
│ target          ┆ x86_64-unknown-linux-gnu │
│ updateAvailable ┆ true                 │
│ updated         ┆ false                │
╰─────────────────┴──────────────────────╯

# Possible representative successful install output
╭─────────────────┬──────────────────────────╮
│ Field           ┆ Value                    │
╞═════════════════╪══════════════════════════╡
│ currentVersion  ┆ 0.4.0                    │
│ latestVersion   ┆ 0.5.0                    │
│ publishedAt     ┆ 2026-09-30T12:00:00Z     │
│ target          ┆ x86_64-unknown-linux-gnu │
│ updateAvailable ┆ false                    │
│ updated         ┆ true                     │
╰─────────────────┴──────────────────────────╯

--check never installs. Plain update prompts when a release is available. Use --yes for an explicit unattended install; machine-readable or non-interactive execution also requires --yes before replacing the executable.

The updater verifies the signed release manifest and the selected archive's SHA-256 digest before installation. No other command contacts the update service.

Revision-Safe Automation

Read a revision, retain it, and pass it to the later mutation:

octarine note read Projects/Launch.md --json
octarine note update Projects/Launch.md \
  --stdin \
  --revision 'sha256:<revision-from-read>' < revised.md

# Read output
{"schemaVersion":1,"ok":true,"data":{"path":"Projects/Launch.md","content":"# Launch\n","revision":"sha256:9be317c2…"},"meta":{"truncated":false}}

# Successful update output
╭──────────┬────────────────────╮
│ Field    ┆ Value              │
╞══════════╪════════════════════╡
│ content  ┆ # Revised launch   │
│ path     ┆ Projects/Launch.md │
│ revision ┆ sha256:a031db82…   │
╰──────────┴────────────────────╯

If the file changed between those commands, the update exits with code 4 and a REVISION_CONFLICT error instead of overwriting newer content. Re-read the note, re-apply your change, and retry with the error's currentRevision.

For small changes, prefer the targeted edit commands. They take the same --revision and return the new revision for the next edit.