chroma-toolkit

Python CLI toolkit for ChromaDB operations, with a stable output contract for automation.

Project health

• Status: v0.1.0.
• Python support: >=3.10.
• Backends: local (PersistentClient) and http (HttpClient).
• Stability target: command behavior and json output shape should stay script-friendly.

What this tool is for

chroma-toolkit helps you manage Chroma resources from the command line:

• server inspection (heartbeat, version)
• collection lifecycle (list, create, info, delete, update)
• document lifecycle (add, get, list, delete, count)
• semantic search (query search)
• plugin registry inspection (plugin list)

Prerequisites

• Python >=3.10
• uv installed

Installation

uv sync

Run the CLI with:

uv run chroma-toolkit --help

Quickstart (local backend)

uv run chroma-toolkit --path ./.chroma server heartbeat --output json
uv run chroma-toolkit --path ./.chroma collection create --name hub --get-or-create --output json
uv run chroma-toolkit --path ./.chroma document add --collection hub --id doc-1 --document "How to deploy" --output json
uv run chroma-toolkit --path ./.chroma document get --collection hub --id doc-1 --output json
uv run chroma-toolkit --path ./.chroma query search --collection hub --text "deploy" --n-results 3 --output json
uv run chroma-toolkit --path ./.chroma plugin list --output json

Quickstart (HTTP backend)

Use this when your Chroma server is running remotely or in another process.

uv run chroma-toolkit --backend http --host 127.0.0.1 --port 8000 server version --output json
uv run chroma-toolkit --backend http --host 127.0.0.1 --port 8000 collection list --output json

Command overview

Global options:

• --path (default ./.chroma)
• --backend {local,http} (default local)
• --host (default 127.0.0.1, used by http backend)
• --port (default 8000, used by http backend)

Command groups:

• server: heartbeat, version
• collection: list, create, info, delete, update
• document: add, get, list, delete, count
• query: search
• plugin: list

Output contract

--output is a command option (not a global option).

• Accepted formats: yaml (default), json, toml
• --output can be provided only once per command

Examples:

uv run chroma-toolkit collection list --output yaml
uv run chroma-toolkit collection list --output json
uv run chroma-toolkit collection list --output toml

All formats use the same logical envelope:

• Success: {"ok": true, "data": <payload>, "error": null}
• Error: {"ok": false, "data": null, "error": {"code": <int>, "message": <str>}}

Notes:

• In toml, null is rendered as the string "null".
• Unknown backend/runtime failures are prefixed with backend: .

Exit codes

• 0: success
• 2: invalid CLI usage (Click)
• 3: backend/runtime error
• 4: resource not found
• 5: validation error

Known limits (v0.1)

• plugin list is available, but end-to-end ingestion/chunking pipeline is not finalized.
• collection list sorts by name and applies limit/offset in CLI code for deterministic output.
• document delete --where may return deleted_count: null when backend delete count is unavailable.

Troubleshooting

• No such option: --output at root:
  • --output must be set on the command itself, for example server version --output json.
• backend: embedding function unavailable... on query search:
  • configure an embedding function on the target collection/backend.
• Collection not found: <name>:
  • check backend selection (local vs http) and collection name.

Contributing

See CONTRIBUTING.md for setup, quality checks, and pull request rules.