CLI Reference#

Global Usage#

cairn [--db <path>] [command] [flags]

Run cairn with no arguments to launch the interactive TUI.

Global Flags#

Commands#

cairn add#

Save a bookmark by URL. The page title and description are fetched automatically.

cairn add <url> [--tags <comma-separated>]

Arguments:

Flags:

Exit codes:

Examples:

cairn add https://go.dev
cairn add https://pkg.go.dev/net/http --tags "go,stdlib"

cairn list#

List all bookmarks.

cairn list [--json] [--order asc|desc]

Flags:

Tab-separated output columns: ID, Title, URL, Domain, CreatedAt

Examples:

cairn list
cairn list --json
cairn list --order asc
cairn list --json | jq '.[0].title'

cairn search#

Search bookmarks by title, domain, and description using full-text search (FTS5) combined with fuzzy matching.

cairn search <query> [--json] [--limit N]

Arguments:

Flags:

Examples:

cairn search golang
cairn search "rust async" --limit 5
cairn search api --json | jq '.[].url'

cairn delete#

Delete a bookmark by its numeric ID.

cairn delete <id>

Arguments:

Exit codes:

Example:

cairn delete 42

cairn pin#

Toggle the pin (permanent) flag on a bookmark. Pinned bookmarks are never auto-archived.

cairn pin <id>

Arguments:

Example:

cairn pin 42   # pins if unpinned, unpins if pinned

cairn sync#

Manage bookmark synchronisation via Dropbox. See Dropbox Sync for setup instructions.

cairn sync <subcommand>

Subcommands:

cairn sync setup#

Connects cairn to Dropbox and performs the initial sync. If CAIRN_DROPBOX_APP_KEY is not set via environment variable or cairn.json, the command prompts interactively:

Enter your Dropbox App Key: <key>
Enter database path (press Enter for default: /home/user/.local/share/cairn/bookmarks.db):

Values entered during the prompt are saved to cairn.json for future runs. The App Key is required for setup and auth; the database path defaults to the platform default if left blank.

You can skip the interactive prompt by supplying the App Key in advance:

export CAIRN_DROPBOX_APP_KEY=<your-app-key>
cairn sync setup

cairn sync auth#

Re-authenticates with Dropbox. Requires CAIRN_DROPBOX_APP_KEY to be set via environment variable or cairn.json (no interactive prompt).

Auto-sync (background)#

When sync is configured, most commands trigger a background sync automatically — no manual cairn sync pull or cairn sync push is needed for routine use.

Background syncs run as a detached subprocess with no output to the terminal. A lock file prevents concurrent syncs. If a sync is already running, the new request is silently skipped.

First-run prompt#

On the very first run (before any sync configuration exists), cairn asks whether you want to set up Dropbox sync:

No sync configured — connect to Dropbox? (y/N)

• Answering y prints instructions to run cairn sync setup.
• Any other response records a declined state so the prompt does not appear again.

cairn update#

Check for and apply updates to the cairn binary or the Vicinae extension. No network requests are ever made by other subcommands — updates are strictly opt-in.

cairn update [--check] [--extension]

Flags:

Flag combinations:

Exit codes:

Example output:

# Update available
$ cairn update
cairn: current version v0.1.0, latest v0.2.0
cairn: downloading cairn-linux-amd64...
cairn: verifying checksum...
cairn: updated to v0.2.0

# Already up to date
$ cairn update
cairn: already up to date (v0.2.0)

# Check only
$ cairn update --check
cairn: current version v0.1.0, latest v0.2.0 (update available)

# Extension not installed
$ cairn update --extension
cairn: extension not installed; run the install script with --with-extension to install it

Notes:

• The existing binary is backed up before replacement and restored if the update fails — your installation is never left in a broken state.
• On Windows, in-process update is not supported. Re-run the install script to update.
• Requires write permission to the directory where cairn is installed (typically ~/.local/bin). If permission is denied, exit code 4 is returned with a descriptive error.

cairn version#

Print the application version.

cairn version

cairn config#

Print the resolved configuration (database path and whether the Dropbox app key is set).

cairn config

Output example (Dropbox key configured):

CAIRN_DB_PATH=/home/user/.local/share/cairn/bookmarks.db
CAIRN_DROPBOX_APP_KEY=(set)

Output example (no Dropbox key):

CAIRN_DB_PATH=/home/user/.local/share/cairn/bookmarks.db

The CAIRN_DROPBOX_APP_KEY line is only printed when the key is set.

cairn help#

Print the top-level help text.

cairn help
cairn --help
cairn -h

Environment Variables#