--- title: Workspaces and Search description: 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. ```bash octarine workspace list octarine workspace list --json --fields name,uuid,path ``` ```text # 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 ` 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. ```text octarine workspace show [identifier] ``` ```bash octarine workspace show "Work Notes" octarine workspace show 018f2c4e-example --json octarine --workspace ~/Notes workspace show ``` ```text # 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](/cli/getting-started#select-a-workspace) 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`. ```text octarine workspace use ``` ```bash octarine workspace use "Work Notes" octarine workspace use ~/Notes ``` ```text ╭───────────┬──────────────────────────────────────────────────────────╮ │ 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 `. `--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. ```bash octarine workspace info "Work Notes" octarine --workspace ~/Notes workspace info --json ``` ```text # 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. ```bash octarine workspace doctor "Work Notes" octarine --workspace ~/Notes workspace doctor --json ``` ```text # 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. ```text octarine search [--limit ] [--cursor ] [--title] [--case-sensitive] [--whole-word] [--regex] [--tag ] [--property ] [--in-path ] [--context-lines ] [--max-output-bytes ] ``` A basic search returns up to 20 matching lines: ```bash octarine search "release candidate" ``` ```text ╭──────┬───────────────────────┬────────────────────────────────────╮ │ 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: ```bash octarine search launch --limit 10 --json octarine search launch --limit 10 --cursor oa --json ``` ```text # 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: ```bash octarine search Launch --title octarine search API --case-sensitive --whole-word octarine search 'v[0-9]+\.[0-9]+' --regex ``` ```text # 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: ```bash octarine search launch --in-path Projects octarine search launch --tag project octarine search launch --property status=active octarine search launch --property due ``` ```text # 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: ```bash octarine search launch \ --context-lines 2 \ --limit 10 \ --max-output-bytes 12000 \ --json ``` ```text {"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.