Workspaces and Search
Discover workspaces, inspect their health, and search indexed note content and metadata.
The desktop app registry is the source for workspace names and UUIDs. Once selected, commands operate directly on the workspace and use its registered SQLite index where supported.
workspace list
List every workspace registered by the desktop app.
octarine workspace list
octarine workspace list --json --fields name,uuid,path# Table output
╭────────────┬──────────────────────────────────────┬────────────────────────╮
│ name ┆ uuid ┆ path │
╞════════════╪══════════════════════════════════════╪════════════════════════╡
│ Work Notes ┆ 018f2c4e-7a91-7000-8000-123456789abc ┆ /Users/you/Work Notes │
╰────────────┴──────────────────────────────────────┴────────────────────────╯
# JSON output
{"schemaVersion":1,"ok":true,"data":[{"name":"Work Notes","uuid":"018f2c4e-7a91-7000-8000-123456789abc","path":"/Users/you/Work Notes"}],"meta":{"truncated":false}}Use --app-store <path> or OCTARINE_APP_STORE only to target a development or isolated registry.
workspace show
Show one registry entry by name, UUID, or selected path. Omit the identifier to inspect the currently selected workspace.
octarine workspace show [identifier]octarine workspace show "Work Notes"
octarine workspace show 018f2c4e-example --json
octarine --workspace ~/Notes workspace show# Registered workspace (table)
╭──────────────┬──────────────────────────────────────╮
│ Field ┆ Value │
╞══════════════╪══════════════════════════════════════╡
│ name ┆ Work Notes │
│ path ┆ /Users/you/Work Notes │
│ resolvedFrom ┆ config │
│ uuid ┆ 018f2c4e-7a91-7000-8000-123456789abc │
╰──────────────┴──────────────────────────────────────╯
# Registered workspace (JSON)
{"schemaVersion":1,"ok":true,"data":{"uuid":"018f2c4e-7a91-7000-8000-123456789abc","name":"Work Notes","path":"/Users/you/Work Notes","resolvedFrom":"config"},"meta":{"truncated":false}}
# Unregistered workspace selected by path
╭──────────────┬──────────────────╮
│ Field ┆ Value │
╞══════════════╪══════════════════╡
│ path ┆ /Users/you/Notes │
│ resolvedFrom ┆ flag │
╰──────────────┴──────────────────╯Without an identifier, resolvedFrom reports which selection rule chose the workspace:
| Value | Rule |
|---|---|
flag | --workspace |
env | OCTARINE_WORKSPACE |
directory | The nearest parent directory containing .octarine |
config | The default saved with workspace use |
only | The only registered workspace |
An unregistered workspace selected by path can still be shown, but only its path is available from the registry view.
workspace use
Save a default workspace so later commands do not need --workspace.
octarine workspace use <name, uuid, or path>octarine workspace use "Work Notes"
octarine workspace use ~/Notes╭───────────┬──────────────────────────────────────────────────────────╮
│ Field ┆ Value │
╞═══════════╪══════════════════════════════════════════════════════════╡
│ config ┆ /Users/you/Library/Application Support/octarine/cli.toml │
│ path ┆ /Users/you/Work Notes │
│ workspace ┆ Work Notes │
╰───────────┴──────────────────────────────────────────────────────────╯workspace is the value that was saved and path is the folder it resolves to. This is the same as octarine config set workspace <value>. --workspace, OCTARINE_WORKSPACE, and an enclosing .octarine folder still take precedence over the saved default. Clear it with octarine config unset workspace.
workspace info
Count notes, files, folders, and total bytes for a workspace.
octarine workspace info "Work Notes"
octarine --workspace ~/Notes workspace info --json# Table output
╭───────────┬──────────────────────────────────────╮
│ Field ┆ Value │
╞═══════════╪══════════════════════════════════════╡
│ files ┆ 18 │
│ folders ┆ 4 │
│ name ┆ Work Notes │
│ notes ┆ 16 │
│ path ┆ /Users/you/Work Notes │
│ sizeBytes ┆ 48231 │
│ uuid ┆ 018f2c4e-7a91-7000-8000-123456789abc │
╰───────────┴──────────────────────────────────────╯
# JSON output
{"schemaVersion":1,"ok":true,"data":{"name":"Notes","uuid":null,"path":"/Users/you/Notes","notes":16,"files":18,"folders":4,"sizeBytes":48231},"meta":{"truncated":false}}workspace doctor
Run structural and metadata checks against a registered or selected workspace.
octarine workspace doctor "Work Notes"
octarine --workspace ~/Notes workspace doctor --json# Table output
╭────────┬─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ Field ┆ Value │
╞════════╪═══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╡
│ path ┆ /Users/you/Work Notes │
│ report ┆ {"folders":4,"healthy":true,"metadata":{"properties.json":"valid","schema.json":"valid","themes.json":"valid","types.json":"valid","views.json":"valid"},"notes":16,"warnings":[]} │
╰────────┴─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
# JSON output
{"schemaVersion":1,"ok":true,"data":{"path":"/Users/you/Notes","report":{"healthy":true,"notes":16,"folders":4,"metadata":{"properties.json":"valid","schema.json":"valid","themes.json":"valid","types.json":"valid","views.json":"valid"},"warnings":[]}},"meta":{"truncated":false}}This is equivalent to top-level doctor for the selected workspace. Workspace registry writes remain app-owned; create, add, rename, remove, and trash are not public commands.
search
Search note lines and filter by headings, paths, tags, or properties.
octarine search <query> [--limit <n>] [--cursor <cursor>]
[--title] [--case-sensitive] [--whole-word] [--regex]
[--tag <tag>] [--property <key[=value]>] [--in-path <folder>]
[--context-lines <n>] [--max-output-bytes <n>]A basic search returns up to 20 matching lines:
octarine search "release candidate"╭──────┬───────────────────────┬────────────────────────────────────╮
│ line ┆ path ┆ text │
╞══════╪═══════════════════════╪════════════════════════════════════╡
│ 8 ┆ Projects/Release.md ┆ The release candidate is approved. │
╰──────┴───────────────────────┴────────────────────────────────────╯When a search fills its --limit, JSON output includes meta.nextCursor. Pass that value back with --cursor to get the next page:
octarine search launch --limit 10 --json
octarine search launch --limit 10 --cursor oa --json# First page
{"schemaVersion":1,"ok":true,"data":[{"path":"Projects/Launch.md","line":1,"text":"# Launch plan"},…],"meta":{"truncated":false,"nextCursor":"oa"}}
# Next page
{"schemaVersion":1,"ok":true,"data":[{"path":"Projects/Launch.md","line":42,"text":"Review the launch checklist."},…],"meta":{"truncated":false,"nextCursor":"o14"}}Treat cursors as opaque values and keep the other search options the same between pages.
Restrict matches to headings or use exact matching rules:
octarine search Launch --title
octarine search API --case-sensitive --whole-word
octarine search 'v[0-9]+\.[0-9]+' --regex# Heading-only search
╭──────┬────────────────────┬───────────────╮
│ line ┆ path ┆ text │
╞══════╪════════════════════╪═══════════════╡
│ 1 ┆ Projects/Launch.md ┆ # Launch plan │
╰──────┴────────────────────┴───────────────╯
# Case-sensitive whole-word search
╭──────┬────────────────────┬────────────────────────╮
│ line ┆ path ┆ text │
╞══════╪════════════════════╪════════════════════════╡
│ 17 ┆ Projects/Launch.md ┆ Confirm the API schema. │
╰──────┴────────────────────┴────────────────────────╯
# Regular-expression search
╭──────┬───────────────────────┬──────────────────────────╮
│ line ┆ path ┆ text │
╞══════╪═══════════════════════╪══════════════════════════╡
│ 5 ┆ Projects/Release.md ┆ Current milestone: v2.4. │
╰──────┴───────────────────────┴──────────────────────────╯Filter notes before matching their content:
octarine search launch --in-path Projects
octarine search launch --tag project
octarine search launch --property status=active
octarine search launch --property due# Path filter
╭──────┬────────────────────┬─────────────────────────────╮
│ line ┆ path ┆ text │
╞══════╪════════════════════╪═════════════════════════════╡
│ 1 ┆ Projects/Launch.md ┆ # Launch plan │
╰──────┴────────────────────┴─────────────────────────────╯
# Tag filter
╭──────┬────────────────────┬─────────────────────────────╮
│ line ┆ path ┆ text │
╞══════╪════════════════════╪═════════════════════════════╡
│ 12 ┆ Projects/Launch.md ┆ Finalize the launch assets. │
╰──────┴────────────────────┴─────────────────────────────╯
# Property value filter
╭──────┬────────────────────┬─────────────────────────────╮
│ line ┆ path ┆ text │
╞══════╪════════════════════╪═════════════════════════════╡
│ 12 ┆ Projects/Launch.md ┆ Finalize the launch assets. │
╰──────┴────────────────────┴─────────────────────────────╯
# Property-presence filter
╭──────┬────────────────────┬─────────────────────────────╮
│ line ┆ path ┆ text │
╞══════╪════════════════════╪═════════════════════════════╡
│ 12 ┆ Projects/Launch.md ┆ Finalize the launch assets. │
╰──────┴────────────────────┴─────────────────────────────╯Return nearby lines and bound machine output:
octarine search launch \
--context-lines 2 \
--limit 10 \
--max-output-bytes 12000 \
--json{"schemaVersion":1,"ok":true,"data":[{"path":"Projects/Launch.md","line":12,"text":"Finalize the launch assets.","context":[{"line":10,"text":"## Checklist"},{"line":11,"text":""},{"line":12,"text":"Finalize the launch assets."},{"line":13,"text":"- [ ] Publish announcement"},{"line":14,"text":"- [ ] Notify support"}]}],"meta":{"truncated":false}}For a registered workspace, search first reconciles the SQLite search_documents index with current Markdown paths, sizes, and modification times. If the database or refresh is unavailable, the command searches live files rather than returning a knowingly stale partial index.