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

# CLI Reference

> Full command reference for auth, workspaces, keys, and filesystem operations.

# Bossa CLI Reference

The Bossa CLI manages accounts, workspaces, API keys, and provides full filesystem access. It is a first-class interface for agents — when your harness runs tools as subprocesses, use `bossa files` for the same operations as MCP.

**Install:** `pip install bossa-memory`

***

## Agent Documentation (`bossa init`)

Add Bossa usage instructions to your agent config files (AGENTS.md, CLAUDE.md, GEMINI.md) so your AI agent knows how to use Bossa.

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
bossa init
```

Scans project and global locations for AGENTS.md, CLAUDE.md, and GEMINI.md, then appends a Bossa section. When multiple files are found, a checkbox list appears: use arrow keys to navigate, Space to toggle, Enter to confirm. In interactive mode, you are also asked how your agent will use Bossa (CLI, MCP, or both). Use flags for non-interactive use:

| Flag           | Description                                                                               |
| -------------- | ----------------------------------------------------------------------------------------- |
| `--project`    | Only project files (./AGENTS.md, ./CLAUDE.md, ./GEMINI.md at project root)                |
| `--global`     | Only global files (\~/.claude/CLAUDE.md, \~/.codex/AGENTS.md, \~/.gemini/GEMINI.md, etc.) |
| `--path PATH`  | Explicit path(s); can repeat for multiple files                                           |
| `--mode`, `-m` | `cli`, `mcp`, or `both` — which instructions to include (default: both)                   |
| `--overwrite`  | Replace existing Bossa section (default: append)                                          |
| `--yes`, `-y`  | Skip confirmation prompt                                                                  |

**Append (default):** Adds the Bossa section to the end of the file. Asks for confirmation unless `--yes`.

**Overwrite:** Use `--overwrite` to update an existing Bossa section. Use this when you upgrade to a new bossa version — the generated content includes version-specific commands and flags. Requires the flag explicitly.

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
# Append to project files
bossa init --project --yes

# Append to specific file
bossa init --path ./AGENTS.md --yes

# Update to latest (e.g. after upgrading bossa)
bossa init --path ./AGENTS.md --overwrite --yes

# MCP-only instructions (for Cursor, Claude, LangChain)
bossa init --path ./AGENTS.md --mode mcp --yes
```

***

## Authentication

| Command        | Description                       |
| -------------- | --------------------------------- |
| `bossa signup` | Create account (email + password) |
| `bossa login`  | Log in                            |
| `bossa logout` | Clear stored credentials          |
| `bossa whoami` | Show current user                 |

Credentials are stored in `~/.config/bossa/credentials` (or `$XDG_CONFIG_HOME/bossa/credentials`).

***

## Workspaces

| Command                          | Description          |
| -------------------------------- | -------------------- |
| `bossa workspaces list`          | List your workspaces |
| `bossa workspaces create <name>` | Create a workspace   |

Requires login (`bossa login`).

***

## Upgrade to Pro

| Command                                          | Description                                                                                 |
| ------------------------------------------------ | ------------------------------------------------------------------------------------------- |
| `bossa billing upgrade [--interval month\|year]` | Open Stripe Checkout in browser to upgrade to Pro. Default: monthly.                        |
| `bossa billing manage`                           | Open Stripe Customer Portal to manage subscription (update payment, view invoices, cancel). |

Requires login (`bossa login`).

***

## Workspace Context (Active Workspace)

Set an active workspace to avoid passing `--key` on every `bossa files` command.

| Command                                     | Description                                                                        |
| ------------------------------------------- | ---------------------------------------------------------------------------------- |
| `bossa workspace use <name> [--key sk-xxx]` | Set active workspace. Provide `--key` to store it, or use a previously stored key. |
| `bossa workspace current`                   | Show active workspace name                                                         |

Config is stored in `~/.config/bossa/config.json` (or `$XDG_CONFIG_HOME/bossa/config.json`).

***

## Usage

| Command                               | Description                                                                                |
| ------------------------------------- | ------------------------------------------------------------------------------------------ |
| `bossa usage [--json] [--key sk-xxx]` | Show account usage and limits (storage, files, requests). Uses API key like `bossa files`. |

Displays a techy panel with progress bars, percentages, remaining counts, and reset info. Use `--json` or `BOSSA_CLI_JSON=1` for machine-readable output with computed fields (`pct_storage`, `remaining_storage_mb`, `reset_utc`, etc.). Exit codes: 0 success, 1 error, 2 auth failure.

***

## API Keys

| Command                                  | Description                                                                                                                    |
| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `bossa keys create <workspace> [--save]` | Create an API key (copy it — shown once). Use `--save` / `-s` to save key to config as active workspace; no copy/paste needed. |
| `bossa keys list <workspace>`            | List keys for a workspace                                                                                                      |
| `bossa keys revoke <workspace> <key_id>` | Revoke a key                                                                                                                   |

Use `--name` with `create` to name the key (default: `default`).

***

## Filesystem Commands

`bossa files` commands use API key from: `--key` > `BOSSA_API_KEY` > `BOSSA_WORKSPACE` (from config) > `config.active_key`. Run `bossa workspace use <name> --key <key>` to avoid passing `--key` on every command. Default API: `BOSSA_API_URL`.

### Agent Mode

* **`--json`** or **`-j`** — Output JSON for machine parsing
* **`BOSSA_CLI_JSON=1`** — All commands return JSON without passing the flag
* **`--safe`** — On read-only commands (`ls`, `read`, `grep`, `glob`, `stat`, `tree`, `du`), signals auto-approval for agent harnesses that gate tool execution
* **Exit codes:** 0 success, 1 error (not found, validation), 2 auth failure

### `ls` — List directory

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
bossa files ls [path]
```

* **path** (default: `/`): Directory to list
* **Output:** One item per line; directories end with `/`
* **JSON** (with `--json` or `BOSSA_CLI_JSON=1`): `{"items": [{"name": "a/", "type": "directory"}, {"name": "b.txt", "type": "file", "size": 1024, "modified": "2026-03-06T10:00:00Z"}]}`

### `read` — Read file

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
bossa files read <path>
```

* **path:** File path
* **Output:** Raw content to stdout (for piping)
* **JSON:** `{"path": "...", "content": "..."}`

### `write` — Write file

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
bossa files write <path> [--content "..." | stdin]
```

* **path:** File path
* **--content, -c:** Content string (or read from stdin)
* **Output:** "Wrote /path" or `{"path": "...", "wrote": true}`

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
echo "Hello" | bossa files write /hello.txt
bossa files write /note.txt --content "Note content"
```

### `grep` — Search contents

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
bossa files grep [pattern] [--path /] [--regex] [--case-sensitive] [--output-mode matches|files_with_matches|count]
```

* **pattern:** Literal or regex pattern (optional if using --all-of/--any-of/--none-of)
* **--path, -p** (default: `/`): Scope to subtree
* **--regex:** Treat pattern as regex
* **--case-sensitive:** Case-sensitive match
* **--whole-word:** Match whole words only
* **--output-mode, -o** (default: `matches`): `matches` | `files_with_matches` | `count`
* **--max-matches** (default: 100): Max results
* **--offset:** Pagination offset
* **--all-of:** All terms must match (AND). Repeatable.
* **--any-of:** At least one term must match (OR). Repeatable.
* **--none-of:** Exclude lines matching any. Repeatable.
* **--context-before:** Lines before each match
* **--context-after:** Lines after each match

### `glob` — Find by pattern

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
bossa files glob <pattern> [--path /]
```

* **pattern:** Glob (e.g. `*.md`, `**/*.py`)
* **--path, -p** (default: `/`): Scope to subtree
* **Output:** One path per line
* **JSON:** `{"paths": ["/a.md", "/b.md"]}`

### `edit` — Replace substring

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
bossa files edit <path> --old <string> --new <string> [--all]
```

* **path:** File path
* **--old, -o:** String to replace
* **--new, -n:** Replacement string
* **--all, -a:** Replace all occurrences (default: first only)

### `stat` — File metadata

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
bossa files stat <path>
```

* **path:** File path
* **Output:** size, modified, created
* **JSON:** `{"path": "...", "size": N, "modified": "...", "created": "..."}`

### `tree` — Directory tree

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
bossa files tree [path] [--depth N]
```

* **path** (default: `/`): Directory to show
* **--depth, -d:** Max depth (default: unlimited)

### `du` — Disk usage

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
bossa files du [path]
```

* **path** (default: `/`): Directory to summarize
* **Output:** Size per directory

### `delete` — Delete file

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
bossa files delete <path>
```

### `put` — Upload single file

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
bossa files put <local_file> [--target /path]
```

* **local\_file:** Local file path
* **--target, -t:** Remote path (default: `/` + basename)

### `batch` — Batch operations

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
bossa files batch
```

Reads JSON lines from stdin. Each line: `{"op": "read"|"write"|"delete", "path": "...", "content": "..."}` (content required for write). Max 100 ops.

### `upload` — Bulk upload

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
bossa files upload <local_path> [--target /prefix] [--include-hidden]
```

* **local\_path:** Directory or file
* **--target, -t:** Remote path prefix
* **--include-hidden:** Include hidden files (`.` prefix)

***

## Environment Variables

| Variable          | Default                   | Description                                      |
| ----------------- | ------------------------- | ------------------------------------------------ |
| `BOSSA_API_URL`   | `https://bossamemory.com` | API base URL                                     |
| `BOSSA_API_KEY`   | —                         | Workspace API key (or use `bossa workspace use`) |
| `BOSSA_WORKSPACE` | —                         | Override active workspace by name                |
| `BOSSA_CLI_JSON`  | —                         | Set to `1` for JSON output from all commands     |
| `BOSSA_TIMEOUT`   | `30`                      | HTTP timeout (seconds)                           |

**Self-hosting:** Set `SUPABASE_URL` and `SUPABASE_ANON_KEY` when using a self-hosted backend.

***

## CLI vs MCP

| Use CLI when                          | Use MCP when                                          |
| ------------------------------------- | ----------------------------------------------------- |
| Your agent runs tools as subprocesses | Your harness supports MCP (Claude, Cursor, LangChain) |
| CLI-based harnesses (beads, etc.)     | You want native tool integration                      |
| You need `--help` discovery           | You use MCP tool descriptors                          |

Both expose the same filesystem operations. See [Agent Integration](AGENT_INTEGRATION) for examples.