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.

Manage public share links

Create a public link for one note, optionally with an expiration:

bm cloud share create research notes/my-idea
bm cloud share create research notes/my-idea --expires-at 2099-12-31

List all links or filter them by project:

bm cloud share list
bm cloud share list --project research

Disable a link without deleting it, enable it again, or update its expiration:

bm cloud share update SHARE_TOKEN --disable
bm cloud share update SHARE_TOKEN --enable
bm cloud share update SHARE_TOKEN --expires-at 2099-12-31
bm cloud share update SHARE_TOKEN --expires-at none

Revoke a link permanently:

bm cloud share revoke SHARE_TOKEN
bm cloud share revoke SHARE_TOKEN --force

Use --workspace <slug> on any share command when the link belongs to a non-default workspace or when a project name is ambiguous. Create resolves the workspace from the explicit option, the project's configured workspace, or your default workspace; the other commands can route by the explicit workspace.

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            # Personal workspaces only — Team push/pull needs no 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

On Team workspaces (v0.23+), push and pull run over the cloud's permissioned WebDAV API — no rclone remote or storage credentials — with each request authorized against your access to the specific project.

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

The Personal-workspace mirror command can delete cloud files, including files that become newly ignored:

bm cloud sync --name research --dry-run
bm cloud sync --name research

Delete only remote files that match this machine's .bmignore:

bm cloud prune --name research --dry-run
bm cloud prune --name research

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