CLI Storage and Safety

The Octarine CLI is local-first. Note content stays in your workspace as Markdown, while compatible indexed and coordination state can be shared with the desktop app through Octarine's SQLite database.

What Remains Portable

Markdown files and the workspace's .octarine files remain the portable source of truth for notes and workspace resources. You can open an unregistered workspace by path and use the CLI without running the desktop app or creating a database entry.

The CLI does not send note content to an Octarine service. The only built-in network operation is the explicit octarine update command. The MCP server communicates only with the client that starts it, over standard input and output.

CLI settings such as the default workspace and output format are stored separately from workspaces, in cli.toml in your user configuration directory. See Set Defaults.

What Uses SQLite

When the workspace is registered in the desktop database, the CLI uses shared native tables where doing so improves consistency or concurrency:

• workspaces resolves the desktop workspace UUID from its path.
• search_documents stores reconciled note bodies and file fingerprints for search.
• workspace_properties stores property definitions while .octarine/properties.json remains the portable copy.
• folder_configs stores folder configuration while retaining a filesystem fallback.
• inbox_state allocates Inbox numbers atomically across CLI processes and the desktop app.

Before a SQLite-backed search, the CLI reconciles the index against current Markdown paths, modification times, and sizes. If a file changes during reconciliation or the refresh cannot complete, the transaction rolls back and search falls back to live files instead of returning a knowingly stale partial index.

Database Selection

The CLI normally locates the desktop database automatically. For development or isolated automation, override it explicitly:

octarine --database /path/to/octarine.sqlite \
  --workspace ~/Notes \
  search launch

Or set it for the current shell:

export OCTARINE_DATABASE=/path/to/octarine.sqlite

The CLI opens only an existing compatible database schema. It never creates or migrates the desktop database, and it refuses schemas newer than the version it understands. Database migrations remain exclusively owned by the desktop app.

If a workspace is not registered in the selected database, commands continue through Markdown and .octarine filesystem storage.

Filesystem Safety

Workspace mutations include safeguards designed for both people and automation:

• Paths are contained within the selected workspace, including symlink checks.
• .octarine cannot be moved or trashed as an ordinary folder.
• Writes use atomic replacement instead of modifying files in place.
• Workspace locks coordinate concurrent mutations.
• Optional revisions prevent lost updates.
• Trash operations are recoverable rather than immediate permanent deletion.
• Note and folder moves and renames update every link that resolves to the moved notes, including wikilinks, embeds, frontmatter links, and relative Markdown links. The desktop app uses the same link resolver.

The CLI does not expose WebView-only state such as open panes, editor sessions, recents, or chat state. That state belongs to the running desktop interface rather than the portable workspace contract.

Back Up A Workspace

Continue backing up the Markdown workspace as you would without the CLI. SQLite search rows are derived and can be reconciled from files. Portable property and folder configuration copies remain under .octarine.

See Storing Data for Octarine's broader desktop storage model and Backup for one workspace backup option.

Quick Answers