--- title: Automation and Maintenance description: Use stable output and errors, manage CLI settings, inspect schemas, export workspaces, diagnose issues, generate completions, and update the CLI. --- ## Machine-Readable Output All commands accept the global output options described in the [command reference](/cli/commands#global-options). When no output option is given, the CLI uses `OCTARINE_FORMAT`, then the `format` setting from [`octarine config`](#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 `keyvalue` line per field. ```bash octarine note list --sort modified --limit 2 | cut -f5 octarine config set format plain ``` ```text Projects/Launch.md Home.md ``` ### JSON `--json` emits a stable envelope with `schemaVersion`, `ok`, `data`, and `meta`. `meta` always includes `truncated`, plus `nextCursor` for a [search](/cli/workspaces-and-search#search) with more results and `requestId` when you pass `--request-id`. Errors use the same envelope with an `error` object; see [Errors](#errors). ```bash octarine note list --json octarine note read Projects/Launch.md --json --request-id agent-42 ``` ```text # `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. ```bash octarine search launch --jsonl octarine task list --todo --format jsonl ``` ```text # 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. ```bash octarine search launch \ --fields path,line,text \ --limit 10 \ --max-output-bytes 12000 \ --json ``` ```text {"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`: ```text {"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 ."},"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: `. 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`. ```text octarine config list octarine config get octarine config set octarine config unset octarine config path ``` ```bash octarine config list octarine config set format json octarine config get format octarine config unset format ``` ```text # `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. ```bash octarine schema list octarine schema list --json ``` ```text # 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. ```bash octarine schema show note octarine schema show theme --json ``` ```text # `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. ```bash octarine export --json > workspace-export.json octarine export --output workspace-export.json ``` ```text # 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. ```bash octarine capabilities octarine capabilities --json ``` ```text # 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`](/cli/notes#note-edit), or `mcp` before starting [`octarine mcp`](/cli/agents-and-mcp#octarine-mcp). ## `doctor` Check the selected workspace's structure and metadata. ```bash octarine doctor --workspace ~/Notes octarine --workspace ~/Notes doctor octarine --workspace "Work Notes" doctor --json ``` ```text # 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 ` 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. ```text octarine completion ``` ```bash 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 ``` ```text 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. ```bash octarine update --check octarine update octarine update --yes --non-interactive ``` ```text # 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: ```bash octarine note read Projects/Launch.md --json octarine note update Projects/Launch.md \ --stdin \ --revision 'sha256:' < revised.md ``` ```text # 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](/cli/notes#targeted-edits). They take the same `--revision` and return the new revision for the next edit.