# Divinci CLI > Official command-line interface for Divinci AI — manage workspaces, chat with AI assistants, search knowledge bases, and control releases from your terminal. The official CLI for Divinci AI. Authenticate once, then manage your entire workspace — chat sessions, knowledge bases, releases, and more — directly from your terminal or CI pipeline. Interactive REPL, one-shot messages, streaming responses, and full conversation history. Search your RAG index, list indexed files, and check processing status. List, inspect, and switch between workspaces. Set a per-project default. View and manage your AI releases. Filter by status, inspect configuration. Make authenticated API requests without writing code — great for exploration and one-offs. Every command supports `--json` output. Pipe to `jq`, use in shell scripts, automate in pipelines. ## Installation ```bash npm install -g @divinci-ai/cli ``` ```bash pnpm add -g @divinci-ai/cli ``` ```bash yarn global add @divinci-ai/cli ``` ```bash npx @divinci-ai/cli ``` ## Quick Start 1. **Authenticate** ```bash divinci auth login ``` You'll be prompted to paste your API key, which is then validated and stored securely in `~/.config/divinci/credentials.json`. 2. **Select a workspace** ```bash divinci workspace list divinci workspace use ws_abc123 ``` Setting a default workspace means you won't need to pass `--workspace` to every subsequent command. 3. **Start chatting** ```bash divinci chat ``` This opens an interactive REPL session. Use `/help` to list session commands, `/new` to start a fresh conversation, and `/exit` to quit. 4. **Send a one-shot message** ```bash divinci chat send "What is the return policy?" --stream ``` Use `--stream` to print tokens as they arrive instead of waiting for the full response. ## Authentication The CLI stores credentials in `~/.config/divinci/credentials.json` with `0600` permissions (readable only by your user account). Named profiles let you work across multiple environments. ```bash # Interactive login — prompts for API key and validates it divinci auth login # Login to a named profile (stored alongside the default) divinci auth login --profile staging # Check who you're authenticated as divinci auth status divinci auth whoami # alias for status # Remove stored credentials divinci auth logout divinci auth logout -y # skip confirmation prompt ``` ## Configuration Configuration sources are resolved in this priority order — higher always wins: | Priority | Source | How to set | |----------|--------|------------| | **1** (highest) | CLI flags | `--api-key`, `--workspace`, `--profile` | | **2** | Environment variables | `DIVINCI_API_KEY`, `DIVINCI_WORKSPACE_ID` | | **3** | Project config file | `.divinci/config.json` in the current directory | | **4** (lowest) | User credentials | `~/.config/divinci/credentials.json` | ### Environment Variables | Variable | Description | |----------|-------------| | `DIVINCI_API_KEY` | API key — required when not using `auth login` | | `DIVINCI_WORKSPACE_ID` | Default workspace for all commands | | `DIVINCI_API_URL` | Override API base URL (default: `https://api.divinci.app`) | | `DIVINCI_PROFILE` | Named profile to load (default: `default`) | ### Project Config File Commit a `.divinci/config.json` to your project to share workspace settings with your whole team: ```json { "workspaceId": "ws_abc123", "apiUrl": "https://api.divinci.app" } ``` Each developer's personal credentials from `~/.config/divinci/credentials.json` are used for the API key — the project config only sets non-secret values. ## Commands Reference ### `auth` — Manage credentials ```bash divinci auth login # Prompt for API key and save it divinci auth login --profile staging # Save to a named profile divinci auth status # Show current auth info divinci auth whoami # Alias for auth status divinci auth logout # Remove default credentials divinci auth logout -y # Remove without confirmation ``` --- ### `chat` — Conversations ```bash # Interactive REPL (supports /help, /new, /exit) divinci chat # Send a message to an existing conversation divinci chat send "Your message here" divinci chat send "Summarize this" --stream # stream tokens # List conversations divinci chat list divinci chat list --limit 20 --offset 40 # View message history for a conversation divinci chat history divinci chat history --limit 50 ``` | Flag | Description | |------|-------------| | `--stream` | Stream response tokens as they arrive | | `--limit ` | Max results to return | | `--offset ` | Skip the first N results (for pagination) | --- ### `rag` — Knowledge Base ```bash # Semantic search across your indexed content divinci rag search "pricing information" divinci rag search "refund policy" --limit 5 --min-score 0.7 # List all indexed files divinci rag files divinci rag files --page 2 --limit 25 --status ready # Check the processing status of a specific file divinci rag status # Source URL backlinks — the page a file links to on chat context bubbles divinci rag set-source-url --file-id --url https://example.com/page divinci rag set-source-url --file-id --clear # Scrape one page, or crawl a whole site, into one or more vector indexes. # --vector accepts a comma-separated list to target multiple indexes # (e.g. a Vectorize + Qdrant + PageIndex trio) in a single pass. divinci rag crawl https://example.com/docs --vector divinci rag crawl https://example.com --vector idA,idB,idC --multi --sitemap --limit 500 # Re-scrape stale pages after the source content changed (ignores the cache): divinci rag crawl https://example.com --vector --multi --force-refresh ``` | Flag | Description | |------|-------------| | `--multi` | Follow links from the URL (site crawl) instead of one page | | `--sitemap` | Discover pages via the site's sitemap (`--multi`) | | `--limit ` | Max pages in `--multi` mode | | `--force-refresh` | Re-fetch every page from its URL, ignoring the cached copy. Use when the source content (or the scraper) changed and you need fresh content. | | `--ignore-saved` | Incremental crawl — **skips** pages already saved for this host (only fetches new paths). Does **not** refresh stale pages; use `--force-refresh` for that. | | `--wait` | Poll until indexed, then run a retrieval-health self-check on the result | :::caution[Scraper choice] `rag crawl` defaults to the free self-hosted `@divinci-ai/fetch-scraper`. Pass `--scraper @mendable/firecrawl` only when you need FireCrawl Cloud's JavaScript rendering — it is **credit-metered**, and a full-site crawl can exhaust an account's monthly credits in minutes. ::: | Flag | Description | |------|-------------| | `--limit ` | Max results | | `--min-score ` | Minimum relevance score (0–1), e.g. `0.7` | | `--page ` | Page number for file listing | | `--status ` | Filter files by status: `ready`, `processing`, `error` | --- ### `release` — Releases ```bash # List and inspect divinci release list divinci release list --status active --limit 10 divinci release get # Create — blank, or fork an existing release divinci release create --name "My Release" divinci release create --name "Arena variant" --from --assistant-id # Create pre-configured with tools discovered from an MCP server divinci release create-from-mcp --url https://mcp.example.com --name "MCP Release" # Update (GET-then-merge; safe for single-field changes) divinci release update --name "Renamed" divinci release update --require-signed-anonymous-chat divinci release update --fallback-assistants '[{"id":"...","finetune":false}]' # Lifecycle divinci release publish divinci release delete # Clone across workspaces divinci release clone --to-workspace --name "Copy" ``` | Flag | Description | |------|-------------| | `--status ` | (`list`) Filter by status: `active`, `draft`, `archived` | | `--limit ` | (`list`) Max results | | `--name ` | (`create`, required) Release name | | `--from ` | (`create`) Fork an existing release — copies RAG, moderation, prefixes, assistant config | | `--assistant-id ` | (`create --from`) Override the forked release's AI Model selection | | `--url ` | (`create-from-mcp`, required) MCP server URL to discover tools from | | `--fallback-assistants ` | (`update`) Ordered fallback model chain | | `--require-signed-anonymous-chat` / `--no-…` | (`update`) Toggle the anonymous-chat HMAC requirement | | `--rerank-max-chunks ` | (`update`) Cap RAG chunks after merge-rerank | | `--ai-gateway` / `--no-ai-gateway` | (`update`) Toggle Cloudflare AI Gateway routing | | `--response-cache` / `--response-cache-ttl ` | (`update`) Public response cache controls | | `--to-workspace ` | (`clone`, required) Destination workspace | | `--rag-id-map ` / `--rag-id-map-file ` | (`clone`) Remap RAG vector ids in the copy | `update` also exposes context-cache (`--context-cache-mode`, `--context-cache-ttl-minutes`, `--adaptive-ttl`, `--no-cache-system-prompt`), RAG-trigger (`--rag-trigger`, `--rag-trigger-min-chars`), and product sub-reply flags — run `divinci release update --help` for the full set. --- ### `terms` — Terms of Service View/accept a release's ToS, and author the workspace's versioned ToS documents. ```bash # Consumer side: check the gate, then accept divinci terms show divinci terms accept # Authoring side: draft → publish (publishing bumps the version; # EVERY user must re-accept before chatting again) divinci terms list divinci terms create --title "Terms" --file ./terms.md divinci terms get divinci terms update --file ./terms-v2.md divinci terms publish ``` --- ### `workspace` — Workspaces Available via both `workspace` and the shorter `ws` alias. ```bash # List available workspaces divinci workspace list divinci ws list --limit 50 # Inspect a specific workspace divinci workspace get # Set the default workspace for all subsequent commands divinci workspace use ``` --- ### `api` — Raw API Requests Make authenticated HTTP requests to any Divinci API endpoint. Useful for exploring endpoints or accessing features not covered by a dedicated command. ```bash # GET request divinci api GET /v1/workspace # POST with a JSON body divinci api POST /v1/chat/message --body '{"content": "Hello"}' # Pass query parameters divinci api GET /v1/files --param limit=10 --param status=ready # Pass custom headers divinci api GET /v1/workspace --header "X-Custom-Header: value" ``` --- ### `config` — Workspace configuration Read or update the current workspace's title and description without leaving the terminal. ```bash divinci config get divinci config set-title "Acme Support Bot" divinci config set-description "Customer-facing support assistant for orders, returns, and product questions." ``` --- ### `group` — User group management Manage user groups within a workspace and invite or remove members. Useful for sharing access with a team. ```bash divinci group list divinci group get divinci group create --name "Engineering" divinci group update --name "Platform Engineering" divinci group delete # Invite a user to a group divinci group invite --email user@example.com # Remove a user from a group divinci group remove-user --user ``` --- ### `permissions` — Permission management Inspect and edit who can do what within a workspace. Permissions can be granted to users, groups, all-logged-in-users, or anonymous visitors. ```bash # List effective permissions on a resource divinci permissions list --resource # Show your own effective permissions divinci permissions mine # Grant or revoke a permission divinci permissions grant --resource --principal --role editor divinci permissions revoke --resource --principal ``` --- ### `byok` — Bring-your-own-key credentials Manage provider credentials per workspace (OpenAI, Anthropic, Neo4j, etc.). Secrets are write-only — listed entries show metadata, never the secret value. ```bash divinci byok list divinci byok get divinci byok create --provider openai --key sk-... divinci byok rotate --key sk-... divinci byok delete ``` --- ### `api-key` — Workspace API keys Long-lived workspace tokens for daemons and CI. Creation and rotation print the secret exactly once — store it immediately. ```bash divinci api-key list divinci api-key create --name "GitHub Actions" divinci api-key rotate divinci api-key delete # Configure per-key request limits divinci api-key request-limit --max-rpm 60 --max-rpd 10000 ``` --- ### `admin` — Platform-admin operations Requires the `platform-admin` role server-side. Most workspace users will see authorization errors here — that's expected. ```bash # Review pending rate-limit upgrade requests divinci admin rate-limit-requests list divinci admin rate-limit-requests list --status pending # Approve or deny a specific request divinci admin rate-limit-requests decide --status approved divinci admin rate-limit-requests decide --status denied --reason "abuse risk" ``` --- ### `training-data` — Generate training data from RAG Generate, list, monitor, and export synthetic training examples derived from your indexed RAG content. Useful as input for `qa` and `fine-tune` workflows. ```bash divinci training-data generate --rag divinci training-data list divinci training-data status divinci training-data export --format jsonl --out ./out.jsonl divinci training-data export-to-rag --rag divinci training-data delete ``` --- ### `qa` — Quality assurance test suites Build, run, and inspect QA test suites against any release. Subdivides into `suites` (definitions), `runs` (executions), and `tests` (cases). ```bash # Suite management divinci qa suites list divinci qa suites get divinci qa suites set-scorers --scorers exactMatch,llmJudge # Run a suite (single or multi-release) divinci qa run --release divinci qa multi-release-run --releases rel_a,rel_b divinci qa estimate-run # dry-run cost estimate divinci qa arena-run --preset # head-to-head arena style # Browse run results divinci qa runs list --suite divinci qa runs get divinci qa runs cancel # Test cases divinci qa tests generate-tests --count 20 divinci qa augment-training-set divinci qa calibrate # Train + snapshot helpers divinci qa train-from-run --out divinci qa snapshot-rag-group --rag divinci qa backfill-release-snapshots # Import / export, ratings, winner picks divinci qa copy-suite-from --to divinci qa export --out ./suite.json divinci qa import ./suite.json divinci qa regenerate divinci qa winner-pick --winner divinci qa list-ratings divinci qa list-winner-picks divinci qa export-edited-responses --out ./edits.jsonl ``` --- ### `fine-tune` — Fine-tuning lifecycle Create, start, and monitor fine-tune jobs. Pair with `training-data` and `qa export-to-qa` for an end-to-end training pipeline. ```bash divinci fine-tune list divinci fine-tune get divinci fine-tune create --base-model --training-data divinci fine-tune start divinci fine-tune status divinci fine-tune cancel divinci fine-tune delete # Cross-feed: fine-tune outputs ↔ QA pipeline divinci fine-tune export-to-qa --suite divinci fine-tune copy-from ``` --- ### `audio` — Audio transcript management Upload and manage audio assets, then turn transcripts into RAG content. ```bash divinci audio list divinci audio get # Get a signed upload URL for direct PUT divinci audio upload-url --content-type audio/mpeg divinci audio delete # Generate a RAG document from an audio transcript divinci audio generate-rag --rag ``` --- ### `style-pattern` — Per-workspace style rules Mirror of the Divinci Agent's `stylePattern*` tools. Manage approved, proposed, and edit-captured style rules that shape model output. Includes a training-run subsurface for promoting captured edits into a fine-tune dataset. ```bash # Rules divinci style-pattern list divinci style-pattern list-proposed divinci style-pattern list-edits divinci style-pattern test-rewrite --text "..." --rule divinci style-pattern approve divinci style-pattern reject divinci style-pattern toggle divinci style-pattern audit # Training runs (capture → export → transition) divinci style-pattern training-run-create divinci style-pattern training-run-list divinci style-pattern training-run-export --out ./run.jsonl divinci style-pattern training-run-transition --to ready ``` --- ### `arena-preset` — Arena preset management Configure the side-by-side variants used by `qa arena-run` and the arena UI. ```bash divinci arena-preset list divinci arena-preset export --out ./preset.json divinci arena-preset clone --to divinci arena-preset update-variant --variant A --model gpt-4o ``` --- ### `notifications` — Notifications & delivery Workspace notifications plus delivery channels (email/webhook) and tag-routing triggers. See [Observability](/server/observability) for the full pipeline. ```bash divinci notifications list --unread divinci notifications counts divinci notifications mark-read # Delivery channels — where notifications get sent divinci notifications channels create --name "Ops" --webhook-url https://ops.example.com/hook --webhook-secret <32+ chars> divinci notifications channels create --name "On-call" --email oncall@example.com divinci notifications channels verify # email channels divinci notifications channels test divinci notifications channels logs # webhook delivery logs # Delivery triggers — tag → channel routing divinci notifications triggers create --title "Escalations" --any-tags urgent --channels ``` --- ### `flagger` — Custom notification flaggers LLM-driven custom notifications: a flagger evaluates chat traffic with your prompt and raises a tagged notification when it flags. ```bash divinci flagger create \ --title "Refund detector" \ --assistant gemini-3-5-flash \ --prefix 'Does this ask for a refund? Reply {"flagged": boolean}' \ --output-keys flagged --tags refund,urgent --flag-input divinci flagger test "I want my money back!" # dry-run (billed) divinci flagger list divinci flagger delete ``` --- ### `feedback` — Message feedback ```bash # List feedback (paginated, filtered) divinci feedback list divinci feedback list --release --sentiment negative --has-text # Aggregate stats (sentiment / source / per-release breakdown) divinci feedback stats # Inspect a single record divinci feedback get ``` | Flag | Description | |------|-------------| | `--release ` | Filter to one release | | `--sentiment ` | Filter by sentiment | | `--source ` | Filter by feedback source | | `--has-text` | Only feedback with a text comment | | `--created-after ` / `--created-before ` | Time-range filter (epoch ms) | | `--page ` / `--limit ` | Pagination | --- ### `analytics` — Product analytics Metrics, trends, per-product performance, A/B experiments, and the conversion funnel for your AI releases. ```bash divinci analytics metrics --time-range 7d divinci analytics trends --granularity daily divinci analytics performance --sort-by ctr --limit 25 divinci analytics experiments --status running divinci analytics funnel ``` --- ### `metrics` — Pipeline telemetry & alerts Per-node latency/error/throughput metrics, CSV export, and custom alert configurations routed to in-app, email, or webhook channels. ```bash divinci metrics pipeline --time-range 24h divinci metrics export --format csv divinci metrics alerts list divinci metrics alerts set --node-type embedding --metric errorRate \ --warning 0.05 --critical 0.2 --webhook https://ops.example.com/alert divinci metrics alerts ack divinci metrics usage # API-key usage stats divinci metrics billing-report # BYOK vs wallet comparison ``` --- ### `trust` — TrustBench (v1 skeletons) ```bash divinci trust benchmarks # List available benchmark definitions divinci trust run # Execute a benchmark run (skeleton) divinci trust list # List your recent runs divinci trust verify # Verify a signed run log ``` ## Global Options These flags work with every command: | Option | Description | |--------|-------------| | `--api-key ` | Override the API key for this single invocation | | `--workspace ` | Override the workspace ID | | `--profile ` | Use a named profile (default: `default`) | | `--api-url ` | Override the API base URL | | `--json` | Output raw JSON — great for scripting | | `--no-color` | Disable ANSI color codes | | `--quiet` | Suppress informational output | | `--verbose` | Print debug information | ## Scripting & CI/CD Every command supports `--json` for machine-readable output, making the CLI composable with standard Unix tools. ```bash # Extract workspace IDs divinci workspace list --json | jq '.[].id' # Get the top RAG search result divinci rag search "shipping policy" --workspace "$WORKSPACE_ID" --json | jq '.[0].content' # Check a file's indexing status in a script STATUS=$(divinci rag status "$FILE_ID" --workspace "$WORKSPACE_ID" --json | jq -r '.status') if [ "$STATUS" = "ready" ]; then echo "File is indexed and ready" fi ``` ### Always pin `--workspace` in automation `divinci workspace use ` writes the default workspace to a **shared, mutable config file** (`~/.config/divinci/credentials.json`). Any other process on the same machine — a teammate's shell, a second CI job, an AI agent session — can change it between your commands, silently pointing the rest of your script at the wrong workspace. ```bash # ❌ Fragile in automation — the default can change under you mid-script divinci workspace use ws_abc123 divinci rag files --json # ✅ Deterministic — every invocation names its workspace divinci rag files --workspace ws_abc123 --json ``` Reserve `workspace use` for interactive shells. In scripts, CI, and agent sessions, pass `--workspace ` (or set `DIVINCI_WORKSPACE_ID` in an isolated environment) on every command. ### CI/CD Authentication Use environment variables — never `divinci auth login` — in automated environments: ```bash export DIVINCI_API_KEY="dv_key_..." export DIVINCI_WORKSPACE_ID="ws_abc123" # Now all commands authenticate automatically divinci rag search "deployment checklist" --json divinci release list --status active --json ``` ### Multi-Environment Profiles Keep separate profiles for different environments: ```bash # One-time setup divinci auth login --profile dev divinci auth login --profile production # Use a specific profile per command divinci workspace list --profile production divinci rag search "docs" --profile dev # Or switch the active profile for a session export DIVINCI_PROFILE=production divinci release list ``` ## Troubleshooting **`Error: No API key found`** Run `divinci auth login` to store credentials, or set the `DIVINCI_API_KEY` environment variable. **`Error: No workspace set`** Run `divinci workspace list` to find your workspace ID, then `divinci workspace use ` to set a default — or pass `--workspace ` to individual commands. **`Error: Unauthorized (401)`** Your API key may be invalid or revoked. Run `divinci auth status` to check, then `divinci auth login` to re-authenticate with a fresh key from the [dashboard](https://app.divinci.ai/settings/api-keys). **`Error: Workspace not found (404)`** The workspace ID stored as your default may no longer exist. Run `divinci workspace list` to see current workspaces and update with `divinci workspace use `. **`divinci: command not found`** The global install directory isn't in your `$PATH`. Run `npm bin -g` (or `pnpm root -g`) to find where global binaries are installed, then add that directory to your shell's `$PATH`. ## Next Steps - [Authentication guide](/getting-started/authentication) — API key types, token scopes, and best practices - [Quick Start](/getting-started/quickstart) — SDK integration alongside the CLI - [API Reference](https://divinci.ai/api/) — Full REST API documentation