---
title: CLI Storage and Safety
description: Understand how the CLI shares SQLite state while keeping Markdown portable and local.
---

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](/cli/agents-and-mcp#octarine-mcp) 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](/cli/getting-started#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:

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

Or set it for the current shell:

```bash
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](/core-concepts/storing-data) for Octarine's broader desktop storage model and [Backup](/backup/git-sync) for one workspace backup option.

#### Quick Answers

### Does the CLI query Octarine's SQLite database?

Yes, for registered workspace discovery, reconciled search, property definitions, folder configuration, and atomic Inbox numbering. Markdown remains the portable source of note content.

### Will the CLI migrate or create my desktop database?

No. Database schema creation and migration remain owned by the desktop app.

### Can the CLI work with a standalone Markdown workspace?

Yes. Unregistered workspaces use Markdown and `.octarine` files without requiring the desktop database.