--- title: "CLI basics" description: "Common commands for projects, notes, and search." canonical_url: "https://docs.basicmemory.com/local/cli-basics" --- # CLI basics > Common commands for projects, notes, and search. The CLI is the fastest way to manage projects and run MCP tools directly from the terminal. ## Use the short alias `bm` is a short alias for `basic-memory`. ## List and create projects ```bash bm project list bm project add "research" ~/Documents/research ``` `bm project add` indexes a local project before it returns, so its notes are searchable right away. For a very large directory, pass `--no-wait` and run `bm project index research` later. Use `bm status --wait` to block until indexing and embeddings settle. ## Set the default project ```bash bm project default "research" ``` ## Search notes ```bash bm tool search-notes "authentication" ``` Semantic search is always on, so plain searches run in **hybrid** mode wherever vector search is available. Queries that use `AND`, `OR`, or `NOT` run as full-text. Use these flags to force a specific retrieval mode: ```bash bm tool search-notes "authentication architecture" --hybrid bm tool search-notes "login flow" --vector ``` Search observations by category (e.g. every `[decision]` you've captured): ```bash bm tool search-notes --entity-type observation --category decision ``` Add `--compact` to get identifiers and metadata without note bodies, which is handy for picking what to read next. ## Browse and grep like a shell New in v0.24, the shell-style verbs read your knowledge base the way you'd read a directory of files. Projects appear as top-level directories. ```bash bm ls # projects, as directories bm ls /research/specs # one folder bm tree /research --depth 2 # folder hierarchy bm tail -n 20 # most recently changed notes bm cat specs/search --section Decisions # one section of a note bm head specs/search -n 5 bm grep "retry" -C 3 # keyword matches with context lines bm grep --semantic "auth token rotation" # rank by meaning instead bm find --meta "status=active" --fields title,priority ``` `bm grep` matches keywords by default, so a pattern that appears in no note returns nothing. `bm find --meta` filters notes by frontmatter (`confidence>0.6`, `priority in high,critical`, `tags has security`). See the [CLI Reference](https://docs.basicmemory.com/reference/cli-reference#shell-style-read-commands) for every flag. ## Read and write notes ```bash bm tool read-note "docs/api-auth" bm tool read-note "docs/api-auth" --start-line 40 --end-line 80 echo "New note content" | bm tool write-note --title "Notes" --folder "drafts" ``` `read-note` accepts a title, permalink, or file path as the identifier. Reading a note that doesn't exist exits with status `1`, so scripts can check `$?`. ## Read the manual Every command and MCP tool has a manual page: ```bash bm man list bm man grep bm man search-notes ``` ## Import documents Turn a PDF, Word, PowerPoint, or CSV file that already lives in a project into a searchable sidecar note: ```bash uv tool install "basic-memory[documents,pdf]" bm import document reports/q3-review.pdf ``` The path is relative to the project root, not your current directory. ## Schema workflows ```bash bm schema infer person bm schema validate person bm schema diff person ``` Infer a schema from existing notes, validate notes against it, and detect drift — see the [Schema System](https://docs.basicmemory.com/concepts/schema-system) for concepts and the full workflow. ## Format files ```bash bm format bm format --project research bm format notes/meeting.md ``` ## Next steps Complete command reference with all options. Learn how assistants use tools locally. ## Sitemap See the full [sitemap](https://docs.basicmemory.com/sitemap.md) for all pages.