# Cloud CLI

> Use Basic Memory Cloud from the terminal for status checks, API keys, sync, routing, recovery, and automation.

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.

<note icon="i-lucide-cloud">

Cloud CLI commands use the same Cloud account, workspaces, projects, and permissions as the web app and hosted MCP endpoint.

</note>

---

## Install and check the CLI

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

```bash
uv tool install basic-memory
```

Confirm the command is available:

```bash
bm --version
```

Update an older install:

```bash
bm update
```

See [Install Basic Memory locally](/local/local-install) for Homebrew and local MCP setup.

---

## Sign in to Cloud

Use browser-based login for an interactive terminal:

```bash
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:

```bash
# 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](/cloud/api-keys) for the full key workflow and security guidance.

---

## Inspect workspaces and projects

List the Cloud workspaces available to your account:

```bash
bm cloud workspace list
```

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

```bash
bm cloud workspace set-default acme
```

List projects across local and Cloud workspaces:

```bash
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:

```bash
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:

```bash
bm cloud share list
bm cloud share list --project research
```

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

```bash
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:

```bash
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.

```bash
# 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](/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`:

```bash
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](/cloud/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:

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

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

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

<warning>

Starting in v0.23, `bm cloud sync` deletes a previously synced cloud file when it becomes ignored by `.bmignore`. Preview the mirror or prune operation before confirming deletion. Additive `bm cloud push` and `bm cloud pull` do not delete destination files.

</warning>

---

## Recover content from the terminal

Cloud snapshots are available from the CLI:

```bash
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](/cloud/cloud-snapshots) and [Recover Notes](/cloud/restore-lost-content).

---

## Related reference

<card-group>
<card icon="i-lucide-terminal" title="CLI Reference" to="/reference/cli-reference">

Complete command and option reference.

</card>

<card icon="i-lucide-key" title="API Keys" to="/cloud/api-keys">

Create keys for automation and bearer-token MCP clients.

</card>

<card icon="i-lucide-route" title="Local & Cloud Routing" to="/cloud/routing">

Choose which projects use local or Cloud operations.

</card>

<card icon="i-lucide-refresh-cw" title="Cloud Sync" to="/cloud/cloud-sync">

Keep local Markdown folders aligned with Cloud projects.

</card>
</card-group>