Cloud CLI

You do not need the CLI to use Basic Memory Cloud. The web app and hosted MCP endpoint are enough for most people.

Install the CLI when you want Cloud to participate in terminal workflows:

• Check Cloud connection and project status.
• Manage API keys for scripts or MCP clients.
• Sync a Cloud project with a local Markdown folder.
• Route selected local projects through Cloud.
• Create and restore Cloud snapshots.
• Automate repeatable knowledge tasks from shell scripts or CI jobs.

Install and check the CLI

If you have not installed Basic Memory locally yet, use uv:

uv tool install basic-memory

Confirm the command is available:

bm --version

Update an older install:

bm update

See Install Basic Memory locally for Homebrew and local MCP setup.

Sign in to Cloud

Use browser-based login for an interactive terminal:

bm cloud login
bm cloud status

bm cloud login authenticates the CLI. It does not automatically move local projects into Cloud or start syncing files.

For automation, scripts, shared terminals, or clients that need bearer-token authentication, use an API key:

# Save an existing key from Settings -> API Keys
bm cloud api-key save bmc_your_key_here

# Or create and save a new key from the CLI
# Requires an active `bm cloud login` session
bm cloud api-key create "work-laptop"

See API Keys for the full key workflow and security guidance.

Inspect workspaces and projects

List the Cloud workspaces available to your account:

bm cloud workspace list

Set the default workspace used by Cloud commands when one is not specified:

bm cloud workspace set-default acme

List projects across local and Cloud workspaces:

bm project list

bm project list is the fastest sanity check when a terminal command or local MCP server is not using the project you expected.

Route selected local projects through Cloud

Routing is for hybrid setups where you have the CLI or a local MCP server installed, but want specific projects to use Cloud.

# Route one project through Cloud
bm project set-cloud research

# Route a project through a specific workspace
bm project set-cloud research --workspace acme

# Return the project to local routing
bm project set-local research --local-path ~/Documents/research

Routing is separate from file sync. A Cloud-routed project can be used by CLI and local MCP commands without keeping a local Markdown mirror.

See Local & Cloud Routing for the routing model, precedence, and troubleshooting.

Sync Cloud with local files

Use Cloud Sync when you want a local Markdown folder and a Cloud project to stay aligned. The additive push and pull commands work the same on personal and team workspaces. These commands assume the Cloud project already exists — create one in the web app or with bm project add research --cloud:

bm cloud setup
bm cloud sync-setup research ~/Documents/research

# Fetch cloud changes, then upload local ones
bm cloud pull --name research
bm cloud push --name research --dry-run
bm cloud push --name research

See Cloud Sync for the full workflow reference, including conflict handling with --on-conflict.

Recover content from the terminal

Cloud snapshots are available from the CLI:

bm cloud snapshot list
bm cloud snapshot create "Before reorganization"
bm cloud snapshot browse SNAPSHOT_ID --prefix research/
bm cloud restore research/important-note.md --snapshot SNAPSHOT_ID

The CLI asks for confirmation before restore operations. Use --force only when you intentionally want to skip confirmation.

See Cloud Snapshots and Recover Notes.

Related reference