> ## Documentation Index
> Fetch the complete documentation index at: https://docs.memvid.com/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI Reference

> Every memvid command, flag, and environment variable

## Install

<Tabs>
  <Tab title="Auto Installer (Recommended)">
    The installer automatically checks for and installs required dependencies (git, node, npm), then installs Memvid globally.

    **macOS / Linux:**

    ```bash theme={null}
    curl -fsSL https://raw.githubusercontent.com/memvid/preflight-installer/main/install.sh | bash
    ```

    **Windows (PowerShell):**

    ```powershell theme={null}
    irm https://raw.githubusercontent.com/memvid/preflight-installer/main/install.ps1 | iex
    ```

    <Note>
      The installer only installs missing tools and asks for confirmation before proceeding.
      [View source on GitHub](https://github.com/memvid/preflight-installer)
    </Note>
  </Tab>

  <Tab title="npm">
    ```bash theme={null}
    npm install -g memvid-cli
    ```
  </Tab>

  <Tab title="Cargo">
    ```bash theme={null}
    cargo install memvid-cli
    ```
  </Tab>

  <Tab title="From Source">
    ```bash theme={null}
    cargo install --path memvid/crates/memvid-cli --force --features parallel_segments,temporal_track
    ```
  </Tab>
</Tabs>

Verify installation:

```bash theme={null}
memvid --version
```

## Global Flags

| Flag                      | Description                                                                   |
| ------------------------- | ----------------------------------------------------------------------------- |
| `-v, --verbose`           | Debug output (repeat to increase)                                             |
| `--embedding-model MODEL` | Embedding model (bge-small, bge-base, nomic, gte-large, openai, openai-large) |
| `--parallel-segments`     | Enable parallel segment building                                              |
| `--json`                  | Output as JSON (available on most commands)                                   |

## Core Workflows

```bash theme={null}
# Create a memory file
memvid create data.mv2 --tier free --size 1GB

# Ingest documents with embeddings
memvid put data.mv2 --input docs/whitepaper.pdf --title "Whitepaper" --label docs --embedding --vector-compression

# Search
memvid find data.mv2 --query "hybrid search" --top-k 5 --json

# Ask with citations
memvid ask data.mv2 --question "What changed last release?" --top-k 6 --mode hybrid --json

# Timeline and replay
memvid timeline data.mv2 --limit 20 --as-of-frame 150

# Inspect a frame
memvid view data.mv2 --frame-id 10 --page 1

# Stats and maintenance
memvid stats data.mv2
memvid verify data.mv2 --deep
memvid doctor data.mv2 --vacuum --rebuild-lex-index --rebuild-vec-index
```

## API Reference

### File Operations

| Command  | Purpose                | Key Flags                                     |
| -------- | ---------------------- | --------------------------------------------- |
| `create` | Create new `.mv2` file | `--tier`, `--size`, `--no-lex`, `--no-vector` |
| `open`   | Inspect metadata       | `--json`                                      |
| `stats`  | Show file statistics   | `--json`                                      |

### Data Operations

| Command     | Purpose                   | Key Flags                                                            |
| ----------- | ------------------------- | -------------------------------------------------------------------- |
| `put`       | Append from file or stdin | `--input`, `--uri`, `--title`, `--embedding`, `--vector-compression` |
| `put-many`  | Batch ingest              | `--input batch.json`, `--compression-level`                          |
| `api-fetch` | Fetch from HTTP + ingest  | `--config`, `--mode`, `--dry-run`                                    |
| `update`    | Replace payload/metadata  | `--frame-id`, `--uri`, `--input`, `--title`                          |
| `delete`    | Remove a frame            | `--frame-id`, `--uri`, `--yes`                                       |

### Search Operations

| Command      | Purpose                  | Key Flags                                      |
| ------------ | ------------------------ | ---------------------------------------------- |
| `find`       | Lexical/hybrid search    | `--query`, `--mode`, `--top-k`, `--scope`      |
| `vec-search` | Search with vector input | `--vector`, `--embedding`                      |
| `ask`        | Retrieval + synthesis    | `--question`, `--mode`, `--top-k`, `--sources` |

### Timeline & View

| Command    | Purpose                    | Key Flags                                    |
| ---------- | -------------------------- | -------------------------------------------- |
| `timeline` | Chronological list         | `--limit`, `--since`, `--until`, `--reverse` |
| `when`     | Temporal phrase resolution | `--on`, `--tz`, `--anchor`, `--window`       |
| `view`     | Render a frame             | `--frame-id`, `--uri`, `--page`, `--play`    |

### Memory Cards & Enrichment

| Command    | Purpose                 | Key Flags                             |
| ---------- | ----------------------- | ------------------------------------- |
| `enrich`   | Extract memory cards    | `--engine`, `--incremental`, `--json` |
| `memories` | View memory cards       | `--entity`, `--slot`, `--json`        |
| `state`    | Get entity state (O(1)) | `--json`                              |
| `facts`    | Audit extracted facts   | `--entity`, `--json`                  |
| `export`   | Export facts            | `--format`, `--entity`                |

### Tables

| Command         | Purpose                | Key Flags                 |
| --------------- | ---------------------- | ------------------------- |
| `tables import` | Import tables from PDF | `--input`, `--embed-rows` |
| `tables list`   | List all tables        | `--json`                  |
| `tables export` | Export table data      | `--table-id`, `--format`  |

### Maintenance

| Command  | Purpose              | Key Flags                                                |
| -------- | -------------------- | -------------------------------------------------------- |
| `verify` | Check file integrity | `--deep`                                                 |
| `doctor` | Repair and optimize  | `--vacuum`, `--rebuild-lex-index`, `--rebuild-vec-index` |
| `who`    | Check file lock      | `--json`                                                 |
| `nudge`  | Release stale lock   |                                                          |

### Tickets & Capacity

| Command         | Purpose               | Key Flags                  |
| --------------- | --------------------- | -------------------------- |
| `tickets sync`  | Sync from dashboard   | `--memory-id`, `--api-key` |
| `tickets apply` | Apply ticket manually | `--ticket`                 |
| `tickets list`  | List current tickets  | `--json`                   |
| `plan show`     | Show current plan     | `--json`                   |

### Sessions

| Command          | Purpose         | Key Flags               |
| ---------------- | --------------- | ----------------------- |
| `session start`  | Start recording | `--name`                |
| `session end`    | End recording   |                         |
| `session list`   | List sessions   | `--json`                |
| `session replay` | Replay session  | `--adaptive`, `--top-k` |

<Note>
  Embeddings are off by default in the CLI to save space. Add `--embedding` (and optionally `--vector-compression`) when you want vectors.
</Note>

## Environment Variables

| Variable                    | Purpose                           | Default            |
| --------------------------- | --------------------------------- | ------------------ |
| `MEMVID_API_KEY`            | Dashboard API key for ticket sync | n/a                |
| `MEMVID_API_URL`            | Control plane base URL            | production URL     |
| `MEMVID_CACHE_DIR`          | Ticket cache directory            | `~/.cache/memvid`  |
| `MEMVID_MODELS_DIR`         | Model cache directory             | `~/.memvid/models` |
| `MEMVID_OFFLINE`            | Skip model downloads              | `0`                |
| `MEMVID_EMBEDDING_MODEL`    | Default embedding model           | `bge-small`        |
| `MEMVID_LLM_CONTEXT_BUDGET` | Max chars to send to LLMs         | unset              |
| `MEMVID_PARALLEL_SEGMENTS`  | Force parallel builder            | unset              |
| `OPENAI_API_KEY`            | OpenAI API key                    | n/a                |
| `ANTHROPIC_API_KEY`         | Anthropic API key                 | n/a                |
| `GEMINI_API_KEY`            | Google Gemini API key             | n/a                |

## Error Codes

| Code  | Name                 | Description                    |
| ----- | -------------------- | ------------------------------ |
| MV001 | CapacityExceeded     | Storage limit reached          |
| MV002 | TicketInvalid        | Invalid ticket signature       |
| MV004 | LexIndexDisabled     | Lexical search not enabled     |
| MV007 | FileLocked           | File locked by another process |
| MV010 | FrameNotFound        | Requested frame doesn't exist  |
| MV011 | VecIndexDisabled     | Vector search not enabled      |
| MV014 | VecDimensionMismatch | Wrong embedding dimension      |
| MV015 | EmbeddingFailed      | Embedding generation failed    |

See [Error Reference](/errors/reference) for complete documentation.

## Tips

* Use `--json` on any command for structured output
* Replay filters: `--as-of-frame` and `--as-of-ts` are available on `find`, `ask`, and `timeline`
* Locks: mutation commands accept `--lock-timeout` and `--force` for stale writers
* `doctor` and `verify` are safe read-only when run with `--plan-only` or `--deep`

<CardGroup cols={2}>
  <Card title="Five-Minute Quickstart" icon="rocket" href="/quickstart/five-minute-guide">
    Fast start for CLI, Python, and Node.js
  </Card>

  <Card title="CLI Commands" icon="terminal" href="/cli/create-and-put">
    Detailed command documentation
  </Card>
</CardGroup>