orchid-cli

Command-line interface for interacting with Orchid without running the API.

orchid-cli runs the full Orchid framework in-process from the terminal — no server, no Docker, no external database required. It imports orchid-ai directly and mirrors the lifecycle of orchid-api, giving you the same agents, tools, RAG, and persistence accessible from a shell script or interactive REPL. The default storage is SQLite (~/.orchid/chats.db); swap in PostgreSQL via orchid-storage-postgres when you need it.

The CLI bundles the orchid-rag-chroma plugin as a dependency for zero-infrastructure RAG — vectors live on disk at ~/.orchid/chroma/, no Qdrant container required. Set VECTOR_BACKEND=qdrant and install orchid-rag-qdrant to switch when you need sparse/hybrid search or scope promotion.

Installation

pip install orchid-ai orchid-cli
# orchid-rag-chroma is included — no extra install needed for on-disk RAG

After installation the `orchid` command is available in your shell.

## Quick start

```bash
# Validate a config before deploying
orchid config validate examples/basketball/orchid.yml

# Start an interactive chat session
orchid chat interactive --config examples/basketball/orchid.yml

# Send a single message and get the response
orchid chat send <chat_id> "Who scored the most points last season?" \
  --config examples/basketball/orchid.yml

Command tree

orchid auth — OAuth 2.0 authentication

Authentication is required when MCP servers or tools need a real Bearer token. When auth.dev_bypass: true is set in the config a dev fallback token is used automatically.

orchid chat — Full CRUD and messaging

orchid config — Validation

Use this in CI pipelines to catch schema errors before deployment.

orchid index — RAG ingestion

orchid skill — Claude Code skill export

orchid generate-flower — Project scaffolding wizard

Interactive wizard that guides you through creating a complete Orchid project skeleton — orchid.yml, agents.yaml, and Python scaffold files — packaged as a zip or written directly to a directory.

The wizard walks through nine phases: project identity, infrastructure (LLM, auth, vector backend, storage), supervisor configuration, agent definitions (repeatable loop), global tools, cross-agent skills, guardrails, events (Pollen + Bloom), and MCP gateway customization. Before generating, a review phase validates all answers against the Pydantic schema and lets you edit any value.

Generated projects include valid orchid.yml and agents.yaml, Python scaffold files for custom agents/tools/identity/hooks/storage, __init__.py files for proper packaging, and a basic test suite. All code follows project SOLID conventions.

orchid mcp — MCP server OAuth

Example session

$ orchid chat interactive --config examples/basketball/orchid.yml

Orchid — interactive mode
Type /help for available commands, /exit to quit.

You: Who has the most career points in NBA history?
[basketball] LeBron James surpassed Kareem Abdul-Jabbar in February 2023...

You: How does that compare to the top three?
[basketball] Here is a comparison of the top three all-time scorers:
  1. LeBron James  —  40,000+ points (active)
  2. Kareem Abdul-Jabbar  —  38,387
  3. Karl Malone  —  36,928

You: /exit
Goodbye.

How the CLI mirrors the API lifespan

orchid-cli/orchid_cli/bootstrap.py performs the same startup sequence as orchid-api/orchid_api/main.py:

1. Load OrchidAgentsConfig from the config path.
2. Call build_graph() to wire the LangGraph supervisor and agent nodes.
3. Initialise OrchidChatStorage (SQLite by default).
4. Warm MCP capability caches for all auth.mode: none servers.

Every chat, index, and mcp command goes through commands/_session.py:resolve_session(), which bootstraps the framework, resolves auth, and warms passthrough/oauth MCP caches once per (tenant_key, user_id). The result is an Orchid facade and an OrchidAuthContext — the same objects the API hands to its routers.

The CLI is an independent OAuth 2.0 client: it runs a full Authorization Code + PKCE flow against the upstream IdP, stores tokens in ~/.orchid/tokens.json (permissions 0o600), and refreshes them automatically when they expire. It never delegates auth to orchid-api.

CLI-specific RAG configuration

When orchid.yml includes a cli_rag: section, the CLI uses it instead of rag:. This lets you run Docker-based examples locally without Qdrant:

rag:
  vector_backend: qdrant           # used by orchid-api (Docker)
  qdrant_url: http://qdrant:6333
  embedding_model: gemini/gemini-embedding-001

cli_rag:
  vector_backend: chroma           # used by orchid-cli (local, on-disk)
  embedding_model: ollama/nomic-embed-text

When cli_rag: is absent, the CLI falls back to rag: as usual. The cli_rag: section supports the same keys as rag:: vector_backend, qdrant_url, embedding_model, openai_api_key, and gemini_api_key.

Precedence: CLI args > env vars > cli_rag: (if present) > rag: > CLI defaults (chroma).