# CLI Reference

> Command-line reference for Basic Memory local and cloud workflows.

Use `bm` (short) or `basic-memory` (full). Examples below use `bm`.

---

## Core commands

### `bm status`

Show the current project-index observation: how many project files were seen, with file details under `--verbose`. The v0.23 display replaces the old sync-report tree; use `--json` for automation.

```bash
bm status
bm status --verbose
bm status --json
bm status --project research
bm status --wait --timeout 60
```

<table>
<thead>
  <tr>
    <th>
      Flag
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        --project
      </code>
    </td>
    
    <td>
      Target a specific project
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --verbose
      </code>
      
      , <code>
        -v
      </code>
    </td>
    
    <td>
      Show detailed file information
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --json
      </code>
    </td>
    
    <td>
      Machine-readable JSON output
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --wait
      </code>
    </td>
    
    <td>
      Poll until sync completes (no pending changes)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --timeout
      </code>
    </td>
    
    <td>
      Deadline in seconds for <code>
        --wait
      </code>
      
       (default <code>
        30
      </code>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --local
      </code>
    </td>
    
    <td>
      Force local routing (ignore cloud mode)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --cloud
      </code>
    </td>
    
    <td>
      Force cloud routing
    </td>
  </tr>
</tbody>
</table>

### `bm doctor`

Run local consistency checks to verify file/database sync. Defaults to local routing since it scans the local filesystem.

```bash
bm doctor
```

<table>
<thead>
  <tr>
    <th>
      Flag
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        --local
      </code>
    </td>
    
    <td>
      Force local routing (ignore cloud mode)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --cloud
      </code>
    </td>
    
    <td>
      Force cloud routing
    </td>
  </tr>
</tbody>
</table>

### `bm mcp`

Run the MCP server with configurable transport options. The server handles initialization, file sync, and cleanup automatically.

```bash
# Default: stdio transport (for Claude Desktop, Claude Code, etc.)
bm mcp

# Lock to a single project
bm mcp --project main

# HTTP transport for web deployments
bm mcp --transport streamable-http --port 8000

# SSE transport for compatibility with existing clients
bm mcp --transport sse
```

<table>
<thead>
  <tr>
    <th>
      Flag
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        --transport
      </code>
    </td>
    
    <td>
      Transport type: <code>
        stdio
      </code>
      
       (default), <code>
        streamable-http
      </code>
      
      , <code>
        sse
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --host
      </code>
    </td>
    
    <td>
      Host for HTTP transports (default <code>
        0.0.0.0
      </code>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --port
      </code>
    </td>
    
    <td>
      Port for HTTP transports (default <code>
        8000
      </code>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --path
      </code>
    </td>
    
    <td>
      Path prefix for streamable-http transport (default <code>
        /mcp
      </code>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --project
      </code>
    </td>
    
    <td>
      Restrict MCP server to a single project
    </td>
  </tr>
</tbody>
</table>

<note>

This command works regardless of cloud mode setting. Users with cloud mode enabled can still run a local MCP server for Claude Code and Claude Desktop.

</note>

### `bm reindex`

Rebuild search indexes and/or vector embeddings without dropping the database.

```bash
# Rebuild everything (search + embeddings)
bm reindex

# Rebuild only full-text search index
bm reindex --search
bm reindex -s

# Rebuild only vector embeddings
bm reindex --embeddings
bm reindex -e

# Reindex a specific project
bm reindex -p main
```

<table>
<thead>
  <tr>
    <th>
      Flag
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        --search
      </code>
      
      , <code>
        -s
      </code>
    </td>
    
    <td>
      Rebuild only the full-text search index
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --embeddings
      </code>
      
      , <code>
        -e
      </code>
    </td>
    
    <td>
      Rebuild only vector embeddings
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --full
      </code>
    </td>
    
    <td>
      Force a complete rebuild and re-embed (the default run is incremental and skips unchanged content)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --project
      </code>
      
      , <code>
        -p
      </code>
    </td>
    
    <td>
      Target a specific project (default: all projects)
    </td>
  </tr>
</tbody>
</table>

When neither `--search` nor `--embeddings` is specified, both are rebuilt.

`bm reindex --embeddings` exits nonzero if any embedding fails and reports the configured vector index. Changing `semantic_vector_index` requires this command; until it succeeds, vector search returns no results and hybrid search serves full-text results only.

### `bm reset`

Reset database — drops all tables and recreates them. Files are never deleted.

```bash
bm reset
bm reset --reindex
```

<table>
<thead>
  <tr>
    <th>
      Flag
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        --reindex
      </code>
    </td>
    
    <td>
      Rebuild the database index from filesystem after reset
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --force
      </code>
    </td>
    
    <td>
      Skip the pre-flight check that refuses to reset while a <code>
        basic-memory mcp
      </code>
      
       process is running. Use only in automation where you've ensured no MCP clients are attached.
    </td>
  </tr>
</tbody>
</table>

<warning>

This rebuilds the entire database from your files. Safe (files are untouched) but may take time for large knowledge bases. `bm reset` refuses to run while an MCP server is attached to the database — stop it first, or pass `--force` in automated workflows.

</warning>

### `bm orphans`

List entities that have no relations — no incoming or outgoing connections in the knowledge graph. Useful for finding notes that aren't yet linked to anything, or notes that had their relations removed.

```bash
bm orphans
bm orphans --json
bm orphans --project research
```

<table>
<thead>
  <tr>
    <th>
      Flag
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        --project
      </code>
    </td>
    
    <td>
      Target a specific project
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --json
      </code>
    </td>
    
    <td>
      Machine-readable JSON output
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --local
      </code>
    </td>
    
    <td>
      Force local routing (ignore cloud mode)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --cloud
      </code>
    </td>
    
    <td>
      Force cloud routing
    </td>
  </tr>
</tbody>
</table>

### `bm update`

Check for a newer Basic Memory release and install it when supported. Basic Memory also checks for updates automatically in the background for Homebrew and `uv tool` installs (uvx environments are skipped — uvx resolves its own cache); MCP server processes check silently and never block.

```bash
# Check for updates and install if available
bm update

# Check only — report without installing
bm update --check
```

<table>
<thead>
  <tr>
    <th>
      Flag
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        --check
      </code>
    </td>
    
    <td>
      Check for updates only; do not install
    </td>
  </tr>
</tbody>
</table>

<note>

Auto-update behavior is configurable — see [Configuration](/reference/configuration) for the `auto_update` and `update_check_interval` settings.

</note>

### `bm format`

Format files using configured formatters. Uses the `formatter_command` or `formatters` settings from your config. By default, formats all `.md`, `.json`, and `.canvas` files in the current project.

```bash
bm format                         # Format all files in current project
bm format --project research      # Format files in specific project
bm format notes/meeting.md        # Format a specific file
bm format notes/                  # Format all files in a directory
```

<table>
<thead>
  <tr>
    <th>
      Flag
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        --project
      </code>
      
      , <code>
        -p
      </code>
    </td>
    
    <td>
      Target a specific project
    </td>
  </tr>
</tbody>
</table>

---

## Retrieval inspection commands

Read-only diagnostics for search, new in v0.23. When a note doesn't come back for a query you expected it to, `bm inspect chunks` answers "is this note indexed, embedded, and current?" and `bm inspect query` answers "what did retrieval actually do with my query?".

### `bm inspect chunks`

Show how the retrieval index decomposes one note into search rows and vector chunks. Accepts the same identifiers as `read_note`: a title, permalink, or `memory://` URL.

```bash
bm inspect chunks "coffee-brewing-methods"
bm inspect chunks "Coffee Brewing Methods" --project research
bm inspect chunks coffee-brewing-methods --json
```

The output shows the note's entity, observation, and relation search rows with the vector chunks each row produced, plus a readiness summary and a per-chunk status:

<table>
<thead>
  <tr>
    <th>
      Status
    </th>
    
    <th>
      Meaning
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        ready
      </code>
    </td>
    
    <td>
      Embedded under the configured model and vector index — visible to vector search
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        pending
      </code>
    </td>
    
    <td>
      Awaiting embedding — not yet visible to vector search
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        stale
      </code>
    </td>
    
    <td>
      The stored chunk no longer matches the note's current search rows
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        orphaned
      </code>
    </td>
    
    <td>
      Embedded under a different model or vector index than the one configured — retrieval cannot see it; rebuild with <code>
        bm reindex --embeddings
      </code>
    </td>
  </tr>
</tbody>
</table>

A freshness state (`fresh`, `not_indexed`, `index_behind_rows`, `rows_behind_file`, or `unknown`) distinguishes a chunking problem from an indexing-lag problem, with the checksum or fingerprint evidence for any non-fresh state.

<table>
<thead>
  <tr>
    <th>
      Flag
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        --json
      </code>
    </td>
    
    <td>
      Output raw JSON — the stable machine-readable schema (automatic when piped)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --plain
      </code>
    </td>
    
    <td>
      Undecorated plain-text output
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --project
      </code>
    </td>
    
    <td>
      Target a specific project
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --project-id
      </code>
    </td>
    
    <td>
      Project external ID (UUID); takes precedence over <code>
        --project
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --local
      </code>
    </td>
    
    <td>
      Force local routing (ignore cloud mode)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --cloud
      </code>
    </td>
    
    <td>
      Force cloud routing
    </td>
  </tr>
</tbody>
</table>

### `bm inspect query`

Run a search and trace its execution: every retrieval stage — matching, hydration, filtering, fusion, reranking, and the final page window — that produced the result page. The trace is captured by the same call that returns the results, so it reflects the actual execution rather than a reconstruction, and ordinary searches are unaffected.

```bash
bm inspect query "how do we handle auth"
bm inspect query "auth" --mode vector --show-misses
bm inspect query "auth" --mode hybrid --page 1 --page-size 10 --json
```

The output shows the engine identity (vector index, embedding model, fusion formula, minimum similarity, reranker status), a stage table with in/out/dropped counts and timings, and the ranked results with final scores and rerank movement (Δ).

<table>
<thead>
  <tr>
    <th>
      Flag
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        --mode
      </code>
    </td>
    
    <td>
      Retrieval mode: <code>
        text
      </code>
      
       (default), <code>
        vector
      </code>
      
      , or <code>
        hybrid
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --show-misses
      </code>
    </td>
    
    <td>
      Also render bounded rejected candidates and why each was dropped (vector and hybrid modes)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --show-ids
      </code>
    </td>
    
    <td>
      Include stable entity IDs in human output
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --page
      </code>
    </td>
    
    <td>
      Result page to inspect (default <code>
        1
      </code>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --page-size
      </code>
    </td>
    
    <td>
      Results per page (default <code>
        10
      </code>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --json
      </code>
    </td>
    
    <td>
      Output raw JSON — every captured candidate, stable schema (automatic when piped)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --plain
      </code>
    </td>
    
    <td>
      Undecorated plain-text output
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --project
      </code>
    </td>
    
    <td>
      Target a specific project
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --project-id
      </code>
    </td>
    
    <td>
      Project external ID (UUID); takes precedence over <code>
        --project
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --local
      </code>
    </td>
    
    <td>
      Force local routing (ignore cloud mode)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --cloud
      </code>
    </td>
    
    <td>
      Force cloud routing
    </td>
  </tr>
</tbody>
</table>

---

## Configuration commands

### `bm config list`

List every scalar setting with its effective value and source. Environment overrides are marked with the exact `BASIC_MEMORY_*` variable.

```bash
bm config list
bm config list --json
```

### `bm config get`

Show one effective value and report any environment override:

```bash
bm config get reranker_enabled
bm config get milvus_uri
```

### `bm config set`

Validate a value through the same config model used at startup, then write it to `config.json`:

```bash
bm config set reranker_enabled true
bm config set cli_output_style plain
```

Invalid keys or values exit nonzero without changing the config file. If an environment variable overrides the file value, the command writes the value but warns that the environment still wins.

### `bm config unset`

Remove a setting from `config.json`:

```bash
bm config unset reranker_enabled
```

The effective value then falls back to an environment override when one exists, otherwise to the built-in default.

`list`, `get`, `set`, and `unset` mask secret values and redact credentials embedded in URLs. Structured fields such as projects are managed by their dedicated command groups and do not appear as writable scalar settings.

---

## Harness hook commands

`bm hook` is the lifecycle front door used by the Basic Memory Claude Code and Codex plugins. See [Harness Capture](/integrations/harness-capture) for event behavior, settings, and retention.

```bash
# Inspect shared inbox and harness settings health
bm hook status --harness codex --project-dir /path/to/repository
bm hook status --harness claude --project-dir /path/to/repository

# Archive local lifecycle envelopes
bm hook flush
bm hook flush --older-than-days 30

# Wire or remove user-level hooks without a plugin
bm hook install --harness codex
bm hook remove --harness codex
bm hook install --harness claude
bm hook remove --harness claude
```

<table>
<thead>
  <tr>
    <th>
      Command
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        session-start
      </code>
    </td>
    
    <td>
      Print the configured context brief and capture a session-start envelope when enabled
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        pre-compact
      </code>
    </td>
    
    <td>
      Capture the compaction event and coordinate a durable checkpoint
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        stop
      </code>
    </td>
    
    <td>
      Compatibility no-op for stale pre-upgrade Stop hooks; not registered by new installs
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        status
      </code>
    </td>
    
    <td>
      Show inbox depth, last flush, settings, capture/checkpoint state, and tool versions
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        flush
      </code>
    </td>
    
    <td>
      Archive pending envelopes locally; never writes graph notes
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        install
      </code>
    </td>
    
    <td>
      Add ownership-tagged user-level harness hooks idempotently
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        remove
      </code>
    </td>
    
    <td>
      Remove only the entries written by <code>
        bm hook install
      </code>
    </td>
  </tr>
</tbody>
</table>

---

## Project management

### `bm project list`

List projects from local config and (when available) cloud.

```bash
bm project list
bm project list --json
bm project list --workspace my-workspace
```

<table>
<thead>
  <tr>
    <th>
      Flag
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        --json
      </code>
    </td>
    
    <td>
      Machine-readable JSON output
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --workspace
      </code>
    </td>
    
    <td>
      Cloud workspace name, slug, type, or tenant ID
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --local
      </code>
    </td>
    
    <td>
      Force local routing
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --cloud
      </code>
    </td>
    
    <td>
      Force cloud routing
    </td>
  </tr>
</tbody>
</table>

### `bm project info`

Display detailed information and statistics about a project. Shows an htop-inspired compact dashboard with horizontal bar charts for note types, embedding coverage bars, and colored status dots.

```bash
bm project info main
bm project info main --json
```

<table>
<thead>
  <tr>
    <th>
      Flag
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        --json
      </code>
    </td>
    
    <td>
      Machine-readable JSON output
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --local
      </code>
    </td>
    
    <td>
      Force local routing (ignore cloud mode)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --cloud
      </code>
    </td>
    
    <td>
      Force cloud routing
    </td>
  </tr>
</tbody>
</table>

### `bm project add`

Add a new project.

```bash
# Local project
bm project add research ~/Documents/research

# Cloud project (no local sync)
bm project add research --cloud

# Cloud project with local sync path
bm project add research --cloud --local-path ~/docs

# Cloud project in a specific team workspace, visible to all members
bm project add team-wiki --cloud --workspace acme --visibility workspace

# Cloud project restricted to specific people you grant access to
bm project add hiring --cloud --workspace acme --visibility shared

# Add and set as default
bm project add research ~/Documents/research --default
```

<table>
<thead>
  <tr>
    <th>
      Flag
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        --local-path
      </code>
    </td>
    
    <td>
      Local sync path for cloud mode
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --workspace
      </code>
    </td>
    
    <td>
      Cloud workspace name, slug, type, or tenant ID (cloud mode only)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --visibility
      </code>
    </td>
    
    <td>
      Cloud project visibility: <code>
        workspace
      </code>
      
       (default — visible to all members), <code>
        shared
      </code>
      
       (restricted to granted users), or <code>
        private
      </code>
      
       (creator only)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --default
      </code>
    </td>
    
    <td>
      Set as default project
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --local
      </code>
    </td>
    
    <td>
      Force local routing
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --cloud
      </code>
    </td>
    
    <td>
      Force cloud routing
    </td>
  </tr>
</tbody>
</table>

### `bm project remove`

Remove a project. Files are retained by default; pass `--delete-notes` to remove them too. For
a cloud project with a configured local sync directory, also pass `--cloud` to remove both the
hosted objects and that local copy.

```bash
# Stop tracking a project while retaining its files
bm project remove research

# Delete a local project's files
bm project remove research --delete-notes

# Purge cloud storage and remove any configured local sync directory
bm project remove research --cloud --delete-notes
```

<table>
<thead>
  <tr>
    <th>
      Flag
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        --delete-notes
      </code>
    </td>
    
    <td>
      Also delete project files: local files for a local project, or all active objects under the project prefix for a cloud project
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --local
      </code>
    </td>
    
    <td>
      Force local routing
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --cloud
      </code>
    </td>
    
    <td>
      Force cloud routing
    </td>
  </tr>
</tbody>
</table>

Cloud deletion is accepted asynchronously. Without `--delete-notes`, the project is removed from the hosted database but its cloud files remain. With `--delete-notes`, the background job purges indexed and unindexed objects under the exact project storage prefix before completing the hard delete. Existing cloud snapshots follow their own retention and deletion lifecycle.

<warning>

For a cloud project configured with a local sync path, explicitly passing both `--cloud` and `--delete-notes` also removes that local sync directory. Back up any local files you need before running the command.

</warning>

### `bm project default`

Set the default project used as fallback when no project is specified.

```bash
bm project default main
```

### `bm project move`

Update a local project's configured filesystem path. This changes configuration only — move the files to the new path yourself (Basic Memory does not move them).

```bash
bm project move research /new/path/to/research
```

### `bm project ls`

List files in a project directory.

```bash
bm project ls --name research
bm project ls --name research subfolder
bm project ls --name research --local
bm project ls --name research --cloud
```

<table>
<thead>
  <tr>
    <th>
      Flag
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        --name
      </code>
    </td>
    
    <td>
      Project name (required)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --local
      </code>
    </td>
    
    <td>
      List files from local instance
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --cloud
      </code>
    </td>
    
    <td>
      List files from cloud instance
    </td>
  </tr>
</tbody>
</table>

### Routing modes (per project)

Route specific projects through cloud while keeping others local:

```bash
bm project set-cloud research
bm project set-local research
```

---

## Cloud commands

### Authentication and status

```bash
bm cloud login
bm cloud status
bm cloud logout
```

### API keys

```bash
bm cloud api-key save bmc_...
bm cloud api-key create "my-laptop"
```

<note>

`bm cloud api-key create` requires an active OAuth session. Run `bm cloud login` first.

</note>

### Setup and upload

```bash
bm cloud setup   # provision the rclone remote (Personal workspaces; Team push/pull needs no setup)
bm cloud upload ~/my-notes --project research --create-project
```

### Sync

```bash
# Fetch cloud changes additively (Personal + Team workspaces)
bm cloud pull --name research

# Upload local changes additively (Personal + Team workspaces)
bm cloud push --name research

# Choose conflict resolution: fail (default) | keep-local | keep-cloud | keep-both
bm cloud pull --name research --on-conflict keep-cloud

# One-way mirror: local → cloud (Personal workspaces only)
bm cloud sync --name research

# Preview and delete cloud files matching ~/.basic-memory/.bmignore (Personal only)
bm cloud prune --name research --dry-run
bm cloud prune --name research

# Verify file integrity between local and cloud (Personal only)
bm cloud check --name research

# Configure local sync for an existing cloud project
bm cloud sync-setup research ~/Documents/research
```

`push`/`pull` are additive (never delete on the destination) and abort on conflicts by default, git-style. On Team workspaces they run over the cloud's permissioned WebDAV API (v0.23+) — no `bm cloud setup` required, and access is checked per project. `sync` is a destructive mirror and is blocked on Team workspaces. In v0.23 it also deletes previously synced files that become ignored by `.bmignore`; preview with `--dry-run`. `prune` performs only that ignore-based remote cleanup and asks for confirmation unless you pass `--yes`. See the [Cloud Sync guide](/cloud/cloud-sync) for details.

### Public shares

```bash
bm cloud share create research notes/my-idea
bm cloud share create research notes/my-idea --expires-at 2099-12-31
bm cloud share list
bm cloud share list --project research
bm cloud share update SHARE_TOKEN --disable
bm cloud share update SHARE_TOKEN --enable
bm cloud share update SHARE_TOKEN --expires-at none
bm cloud share revoke SHARE_TOKEN
bm cloud share revoke SHARE_TOKEN --force
```

All share commands accept `--workspace` to route by workspace slug, display name, or tenant ID. `revoke` confirms before deletion unless `--force` is set.

### Snapshots

```bash
bm cloud snapshot create "Before migration"
bm cloud snapshot list
bm cloud snapshot show <snapshot-id>
bm cloud snapshot browse <snapshot-id>
bm cloud snapshot delete <snapshot-id>
```

### Restore

```bash
bm cloud restore <path> --snapshot <snapshot-id>
```

### Workspaces

```bash
# List cloud workspaces available to the current session
bm cloud workspace list

# Set the default workspace for CLI and MCP routing
bm cloud workspace set-default acme
```

See [Teams](/teams/about) for working with shared team workspaces.

### Promo controls

```bash
bm cloud promo --off
bm cloud promo --on
```

---

## Schema commands

Tools for defining, validating, and evolving note structure. See [Schema System](/concepts/schema-system) for concepts and workflow.

### `bm schema validate`

Validate notes against their schema definition. Pass a note type to validate all notes of that type, a specific file path to validate one note, or omit to validate all notes that have schemas.

```bash
# Validate all notes with schemas
bm schema validate

# Validate all notes of a type
bm schema validate person

# Validate one specific note
bm schema validate people/ada-lovelace.md

# Strict mode — exit 1 if any validation errors are found
bm schema validate person --strict

# Machine-readable output
bm schema validate person --json

# Target a specific project
bm schema validate person --project research
```

<table>
<thead>
  <tr>
    <th>
      Flag
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        --strict
      </code>
    </td>
    
    <td>
      Exit with code 1 if any validation errors are found (warnings never affect the exit code)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --json
      </code>
    </td>
    
    <td>
      Machine-readable JSON output
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --project
      </code>
    </td>
    
    <td>
      Target a specific project
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --local
      </code>
    </td>
    
    <td>
      Force local routing
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --cloud
      </code>
    </td>
    
    <td>
      Force cloud routing
    </td>
  </tr>
</tbody>
</table>

### `bm schema infer`

Analyze existing notes of a type and suggest a schema based on common observation categories, relation types, and frontmatter fields. Fields present in 95%+ of notes become required; fields above the threshold become optional.

```bash
# Infer schema for a note type
bm schema infer person

# Lower the threshold to include less common fields
bm schema infer person --threshold 0.1

# Machine-readable output
bm schema infer person --json

# Target a specific project
bm schema infer person --project research
```

<table>
<thead>
  <tr>
    <th>
      Flag
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        --threshold
      </code>
    </td>
    
    <td>
      Minimum field frequency for inclusion (default <code>
        0.25
      </code>
      
       — fields in 25%+ of notes)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --save
      </code>
    </td>
    
    <td>
      Save the inferred schema as a schema note in the <code>
        schemas/
      </code>
      
       directory
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --json
      </code>
    </td>
    
    <td>
      Machine-readable JSON output
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --project
      </code>
    </td>
    
    <td>
      Target a specific project
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --local
      </code>
    </td>
    
    <td>
      Force local routing
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --cloud
      </code>
    </td>
    
    <td>
      Force cloud routing
    </td>
  </tr>
</tbody>
</table>

### `bm schema diff`

Compare a schema definition against actual note usage to detect drift. Shows new fields appearing, old fields disappearing, and cardinality changes.

```bash
# Check drift for a note type
bm schema diff person

# Machine-readable output
bm schema diff person --json

# Target a specific project
bm schema diff person --project research
```

<table>
<thead>
  <tr>
    <th>
      Flag
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        --json
      </code>
    </td>
    
    <td>
      Machine-readable JSON output
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --project
      </code>
    </td>
    
    <td>
      Target a specific project
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --local
      </code>
    </td>
    
    <td>
      Force local routing
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --cloud
      </code>
    </td>
    
    <td>
      Force cloud routing
    </td>
  </tr>
</tbody>
</table>

---

## Tool commands (CLI wrapper for MCP tools)

Command group: `bm tool` (singular). This provides CLI access to the same MCP tools that AI assistants use, useful for scripting, debugging, and quick operations from the terminal.

Search, read, context, and activity commands use Rich tables, panels, trees, or Markdown when stdout is a TTY. Output precedence is:

1. `--json` for raw machine-readable JSON.
2. `--plain` for undecorated human-readable text.
3. Non-TTY output defaults to JSON, preserving piped and redirected scripts.
4. TTY output follows `cli_output_style` (`rich` by default, or `plain`).

`--json` and `--plain` are mutually exclusive. Set the interactive default with `bm config set cli_output_style plain`.

### `bm tool write-note`

```bash
# Create a note with inline content
bm tool write-note --title "API Notes" --folder specs --content "# API Notes"

# Pipe content from stdin
echo "# My Note" | bm tool write-note --title "My Note" --folder notes

# Set the note type at creation time
bm tool write-note --title "Standup" --folder meetings --type meeting

# Replace an existing note (past the overwrite guard)
bm tool write-note --title "API Notes" --folder specs --content "..." --overwrite
```

<table>
<thead>
  <tr>
    <th>
      Flag
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        --title
      </code>
    </td>
    
    <td>
      Note title (required)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --folder
      </code>
    </td>
    
    <td>
      Destination folder (required)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --content
      </code>
    </td>
    
    <td>
      Note content (reads from stdin if omitted)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --tags
      </code>
    </td>
    
    <td>
      Tags to apply
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --type
      </code>
    </td>
    
    <td>
      Frontmatter note type (e.g. <code>
        meeting
      </code>
      
      , <code>
        task
      </code>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --overwrite
      </code>
    </td>
    
    <td>
      Replace an existing note at the same path (past the overwrite guard)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --project
      </code>
    </td>
    
    <td>
      Target project
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --local
      </code>
    </td>
    
    <td>
      Force local routing
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --cloud
      </code>
    </td>
    
    <td>
      Force cloud routing
    </td>
  </tr>
</tbody>
</table>

### `bm tool read-note`

```bash
bm tool read-note "specs/api-notes"
bm tool read-note my-note --include-frontmatter
```

<table>
<thead>
  <tr>
    <th>
      Flag
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        --include-frontmatter
      </code>
    </td>
    
    <td>
      Include YAML frontmatter in output
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --project
      </code>
    </td>
    
    <td>
      Target project
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --local
      </code>
    </td>
    
    <td>
      Force local routing
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --cloud
      </code>
    </td>
    
    <td>
      Force cloud routing
    </td>
  </tr>
</tbody>
</table>

### `bm tool edit-note`

```bash
bm tool edit-note my-note --operation append --content "new content"
bm tool edit-note my-note --operation find_replace --find-text "old" --content "new"
bm tool edit-note my-note --operation replace_section --section "## Notes" --content "updated"
bm tool edit-note my-note --operation replace_section --section "## Notes" --content "updated" --no-replace-subsections
```

<table>
<thead>
  <tr>
    <th>
      Flag
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        --operation
      </code>
    </td>
    
    <td>
      Edit operation: <code>
        append
      </code>
      
      , <code>
        prepend
      </code>
      
      , <code>
        find_replace
      </code>
      
      , <code>
        replace_section
      </code>
      
      , <code>
        insert_before_section
      </code>
      
      , <code>
        insert_after_section
      </code>
      
       (required; the insert operations also require <code>
        --section
      </code>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --content
      </code>
    </td>
    
    <td>
      Content for the edit (required)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --find-text
      </code>
    </td>
    
    <td>
      Text to find (required for <code>
        find_replace
      </code>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --section
      </code>
    </td>
    
    <td>
      Section heading (required for <code>
        replace_section
      </code>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --expected-replacements
      </code>
    </td>
    
    <td>
      Expected replacement count for <code>
        find_replace
      </code>
      
       (default <code>
        1
      </code>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --replace-subsections
      </code>
      
      , <code>
        --no-replace-subsections
      </code>
    </td>
    
    <td>
      For <code>
        replace_section
      </code>
      
      , replace nested subsections by default or preserve them with <code>
        --no-replace-subsections
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --project
      </code>
    </td>
    
    <td>
      Target project
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --local
      </code>
    </td>
    
    <td>
      Force local routing
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --cloud
      </code>
    </td>
    
    <td>
      Force cloud routing
    </td>
  </tr>
</tbody>
</table>

### `bm tool delete-note`

```bash
bm tool delete-note notes/old-draft
bm tool delete-note docs/archive --is-directory
```

<table>
<thead>
  <tr>
    <th>
      Flag
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        --is-directory
      </code>
    </td>
    
    <td>
      Delete a directory instead of a single note
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --project
      </code>
    </td>
    
    <td>
      Target project
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --project-id
      </code>
    </td>
    
    <td>
      Project external ID (UUID); takes precedence over <code>
        --project
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --local
      </code>
    </td>
    
    <td>
      Force local routing
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --cloud
      </code>
    </td>
    
    <td>
      Force cloud routing
    </td>
  </tr>
</tbody>
</table>

### `bm tool search-notes`

```bash
# Text search (query is a positional argument)
bm tool search-notes "authentication"

# Tag and metadata filters (query is optional)
bm tool search-notes --tag python --tag async
bm tool search-notes --meta status=draft
bm tool search-notes --type person --type meeting

# Search observations by category
bm tool search-notes "auth" --entity-type observation --category decision

# Search modes
bm tool search-notes "how to speed up the app" --hybrid
bm tool search-notes "how to speed up the app" --vector
bm tool search-notes --permalink "specs/*"
bm tool search-notes --title "API Design"

# Advanced metadata filter (JSON)
bm tool search-notes --filter '{"priority": {"$in": ["high", "critical"]}}'

# Pagination
bm tool search-notes "api" --page 2 --page-size 20
```

<table>
<thead>
  <tr>
    <th>
      Flag
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        --hybrid
      </code>
    </td>
    
    <td>
      Use hybrid search (keyword + semantic)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --vector
      </code>
    </td>
    
    <td>
      Use vector (semantic-only) search
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --permalink
      </code>
    </td>
    
    <td>
      Search permalink values
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --title
      </code>
    </td>
    
    <td>
      Search title values
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --tag
      </code>
    </td>
    
    <td>
      Filter by frontmatter tag (repeatable)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --status
      </code>
    </td>
    
    <td>
      Filter by frontmatter status
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --type
      </code>
    </td>
    
    <td>
      Filter by frontmatter type (repeatable)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --entity-type
      </code>
    </td>
    
    <td>
      Filter by result type: <code>
        entity
      </code>
      
      , <code>
        observation
      </code>
      
      , <code>
        relation
      </code>
      
       (repeatable)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --category
      </code>
    </td>
    
    <td>
      Filter observation results to exact categories (repeatable)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --meta
      </code>
    </td>
    
    <td>
      Filter by frontmatter <code>
        key=value
      </code>
      
       (repeatable)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --filter
      </code>
    </td>
    
    <td>
      JSON metadata filter (advanced)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --after_date
      </code>
    </td>
    
    <td>
      Date filter (e.g., <code>
        2d
      </code>
      
      , <code>
        1 week
      </code>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --page
      </code>
    </td>
    
    <td>
      Page number (default <code>
        1
      </code>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --page-size
      </code>
    </td>
    
    <td>
      Results per page (default <code>
        10
      </code>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --project
      </code>
    </td>
    
    <td>
      Target project
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --local
      </code>
    </td>
    
    <td>
      Force local routing
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --cloud
      </code>
    </td>
    
    <td>
      Force cloud routing
    </td>
  </tr>
</tbody>
</table>

### `bm tool build-context`

```bash
bm tool build-context memory://specs/search
bm tool build-context specs/search --depth 2 --timeframe 30d
```

<table>
<thead>
  <tr>
    <th>
      Flag
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        --depth
      </code>
    </td>
    
    <td>
      Traversal depth (default <code>
        1
      </code>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --timeframe
      </code>
    </td>
    
    <td>
      Time window filter (default <code>
        7d
      </code>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --page
      </code>
    </td>
    
    <td>
      Page number (default <code>
        1
      </code>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --page-size
      </code>
    </td>
    
    <td>
      Results per page (default <code>
        10
      </code>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --max-related
      </code>
    </td>
    
    <td>
      Maximum related items (default <code>
        10
      </code>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --project
      </code>
    </td>
    
    <td>
      Target project
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --local
      </code>
    </td>
    
    <td>
      Force local routing
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --cloud
      </code>
    </td>
    
    <td>
      Force cloud routing
    </td>
  </tr>
</tbody>
</table>

### `bm tool recent-activity`

```bash
bm tool recent-activity
bm tool recent-activity --timeframe 30d --page-size 20
bm tool recent-activity --type entity --type observation
```

<table>
<thead>
  <tr>
    <th>
      Flag
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        --type
      </code>
    </td>
    
    <td>
      Filter by item type (repeatable)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --depth
      </code>
    </td>
    
    <td>
      Context depth (default <code>
        1
      </code>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --timeframe
      </code>
    </td>
    
    <td>
      Time window (default <code>
        7d
      </code>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --page
      </code>
    </td>
    
    <td>
      Page number (default <code>
        1
      </code>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --page-size
      </code>
    </td>
    
    <td>
      Results per page (default <code>
        10
      </code>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --project
      </code>
    </td>
    
    <td>
      Target project
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --local
      </code>
    </td>
    
    <td>
      Force local routing
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --cloud
      </code>
    </td>
    
    <td>
      Force cloud routing
    </td>
  </tr>
</tbody>
</table>

### Schema tool commands

These are CLI wrappers around the schema MCP tools with JSON output:

```bash
bm tool schema-validate person
bm tool schema-infer person
bm tool schema-diff person
bm tool list-projects
bm tool list-workspaces
```

---

## Import commands

```bash
bm import claude conversations
bm import claude projects
bm import chatgpt
bm import memory-json /path/to/export.json
```

---

## Notes on defaults

- If `--project` is omitted, Basic Memory falls back to `default_project` when configured.
- Most `bm tool` subcommands accept `--project-id` (the project's external UUID from `bm project list --json`) to disambiguate same-named projects across cloud workspaces.
- `--local` and `--cloud` flags are available on most commands for routing overrides.

---

## Related pages

- [Configuration](/reference/configuration)
- [MCP Tools Reference](/reference/mcp-tools-reference)
- [Cloud Guide](/cloud/cloud-guide)
- [Schema System](/concepts/schema-system)
- [Semantic Search](/concepts/semantic-search)