Skip to content

1.cli-reference.md

Latest commit

 

History

History
697 lines (515 loc) · 20.6 KB

1.cli-reference.md

File metadata and controls

697 lines (515 loc) · 20.6 KB
Raw
title CLI Reference
description 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 sync status between files and database.

bm status
bm status --verbose
bm status --json
bm status --project research
bm status --wait --timeout 60
Flag Description
--project Target a specific project
--verbose, -v Show detailed file information
--json Machine-readable JSON output
--wait Poll until sync completes (no pending changes)
--timeout Deadline in seconds for --wait (default 30)
--local Force local routing (ignore cloud mode)
--cloud Force cloud routing

bm doctor

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

bm doctor
Flag Description
--local Force local routing (ignore cloud mode)
--cloud Force cloud routing

bm mcp

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

# 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
Flag Description
--transport Transport type: stdio (default), streamable-http, sse
--host Host for HTTP transports (default 0.0.0.0)
--port Port for HTTP transports (default 8000)
--path Path prefix for streamable-http transport (default /mcp)
--project Restrict MCP server to a single project

::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. ::

bm reindex

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

# 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
Flag Description
--search, -s Rebuild only the full-text search index
--embeddings, -e Rebuild only vector embeddings
--full Force a complete rebuild and re-embed (the default run is incremental and skips unchanged content)
--project, -p Target a specific project (default: all projects)

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

bm reset

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

bm reset
bm reset --reindex
Flag Description
--reindex Rebuild the database index from filesystem after reset
--force Skip the pre-flight check that refuses to reset while a basic-memory mcp process is running. Use only in automation where you've ensured no MCP clients are attached.

::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. ::

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.

bm orphans
bm orphans --json
bm orphans --project research
Flag Description
--project Target a specific project
--json Machine-readable JSON output
--local Force local routing (ignore cloud mode)
--cloud Force cloud routing

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.

# Check for updates and install if available
bm update

# Check only — report without installing
bm update --check
Flag Description
--check Check for updates only; do not install

::note Auto-update behavior is configurable — see Configuration for the auto_update and update_check_interval settings. ::

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.

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
Flag Description
--project, -p Target a specific project

Project management

bm project list

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

bm project list
bm project list --json
bm project list --workspace my-workspace
Flag Description
--json Machine-readable JSON output
--workspace Cloud workspace name, slug, type, or tenant ID
--local Force local routing
--cloud Force cloud routing

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.

bm project info main
bm project info main --json
Flag Description
--json Machine-readable JSON output
--local Force local routing (ignore cloud mode)
--cloud Force cloud routing

bm project add

Add a new project.

# 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
Flag Description
--local-path Local sync path for cloud mode
--workspace Cloud workspace name, slug, type, or tenant ID (cloud mode only)
--visibility Cloud project visibility: workspace (default — visible to all members), shared (restricted to granted users), or private (creator only)
--default Set as default project
--local Force local routing
--cloud Force cloud routing

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.

# 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
Flag Description
--delete-notes Also delete project files: local files for a local project, or all active objects under the project prefix for a cloud project
--local Force local routing
--cloud Force cloud routing

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. ::

bm project default

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

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).

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

bm project ls

List files in a project directory.

bm project ls --name research
bm project ls --name research subfolder
bm project ls --name research --local
bm project ls --name research --cloud
Flag Description
--name Project name (required)
--local List files from local instance
--cloud List files from cloud instance

Routing modes (per project)

Route specific projects through cloud while keeping others local:

bm project set-cloud research
bm project set-local research

Cloud commands

Authentication and status

bm cloud login
bm cloud status
bm cloud logout

API keys

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. ::

Setup and upload

bm cloud setup
bm cloud upload ~/my-notes --project research --create-project

Sync

# 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

# 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. sync is a destructive mirror and is blocked on Team workspaces. See the Cloud Sync guide for details.

Snapshots

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

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

Workspaces

# 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 for working with shared team workspaces.

Promo controls

bm cloud promo --off
bm cloud promo --on

Schema commands

Tools for defining, validating, and evolving note structure. See 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.

# 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
Flag Description
--strict Exit with code 1 if any validation errors are found (warnings never affect the exit code)
--json Machine-readable JSON output
--project Target a specific project
--local Force local routing
--cloud Force cloud routing

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.

# 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
Flag Description
--threshold Minimum field frequency for inclusion (default 0.25 — fields in 25%+ of notes)
--save Save the inferred schema as a schema note in the schemas/ directory
--json Machine-readable JSON output
--project Target a specific project
--local Force local routing
--cloud Force cloud routing

bm schema diff

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

# 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
Flag Description
--json Machine-readable JSON output
--project Target a specific project
--local Force local routing
--cloud Force cloud routing

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.

bm tool write-note

# 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
Flag Description
--title Note title (required)
--folder Destination folder (required)
--content Note content (reads from stdin if omitted)
--tags Tags to apply
--type Frontmatter note type (e.g. meeting, task)
--overwrite Replace an existing note at the same path (past the overwrite guard)
--project Target project
--local Force local routing
--cloud Force cloud routing

bm tool read-note

bm tool read-note "specs/api-notes"
bm tool read-note my-note --include-frontmatter
Flag Description
--include-frontmatter Include YAML frontmatter in output
--project Target project
--local Force local routing
--cloud Force cloud routing

bm tool edit-note

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"
Flag Description
--operation Edit operation: append, prepend, find_replace, replace_section, insert_before_section, insert_after_section (required; the insert operations also require --section)
--content Content for the edit (required)
--find-text Text to find (required for find_replace)
--section Section heading (required for replace_section)
--expected-replacements Expected replacement count for find_replace (default 1)
--project Target project
--local Force local routing
--cloud Force cloud routing

bm tool delete-note

bm tool delete-note notes/old-draft
bm tool delete-note docs/archive --is-directory
Flag Description
--is-directory Delete a directory instead of a single note
--project Target project
--project-id Project external ID (UUID); takes precedence over --project
--local Force local routing
--cloud Force cloud routing

bm tool search-notes

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

bm tool build-context

bm tool build-context memory://specs/search
bm tool build-context specs/search --depth 2 --timeframe 30d
Flag Description
--depth Traversal depth (default 1)
--timeframe Time window filter (default 7d)
--page Page number (default 1)
--page-size Results per page (default 10)
--max-related Maximum related items (default 10)
--project Target project
--local Force local routing
--cloud Force cloud routing

bm tool recent-activity

bm tool recent-activity
bm tool recent-activity --timeframe 30d --page-size 20
bm tool recent-activity --type entity --type observation
Flag Description
--type Filter by item type (repeatable)
--depth Context depth (default 1)
--timeframe Time window (default 7d)
--page Page number (default 1)
--page-size Results per page (default 10)
--project Target project
--local Force local routing
--cloud Force cloud routing

Schema tool commands

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

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

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