Divinci CLI

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.

Chat

Interactive REPL, one-shot messages, streaming responses, and full conversation history.

Knowledge Base

Search your RAG index, list indexed files, and check processing status.

Workspaces

List, inspect, and switch between workspaces. Set a per-project default.

Releases

View and manage your AI releases. Filter by status, inspect configuration.

Raw API Access

Make authenticated API requests without writing code — great for exploration and one-offs.

Scripting & CI/CD

Every command supports --json output. Pipe to jq, use in shell scripts, automate in pipelines.

Installation

npm install -g @divinci-ai/cli

pnpm add -g @divinci-ai/cli

yarn global add @divinci-ai/cli

npx @divinci-ai/cli <command>

Quick Start

Authenticate
Terminal window
```
divinci auth login
```
You’ll be prompted to paste your API key, which is then validated and stored securely in ~/.config/divinci/credentials.json.

Get your API key from the Divinci dashboard. Keys look like dv_key_....
Select a workspace
Terminal window
```
divinci workspace list
divinci workspace use ws_abc123
```
Setting a default workspace means you won’t need to pass --workspace to every subsequent command.
Start chatting
Terminal window
```
divinci chat
```
This opens an interactive REPL session. Use /help to list session commands, /new to start a fresh conversation, and /exit to quit.
Send a one-shot message
Terminal window
```
divinci chat send <transcriptId> "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.

# 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:

{
  "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

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

# Interactive REPL (supports /help, /new, /exit)
divinci chat

# Send a message to an existing conversation
divinci chat send <transcriptId> "Your message here"
divinci chat send <transcriptId> "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 <transcriptId>
divinci chat history <transcriptId> --limit 50

Flag	Description
`--stream`	Stream response tokens as they arrive
`--limit <n>`	Max results to return
`--offset <n>`	Skip the first N results (for pagination)

`rag` — Knowledge Base

# 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 <fileId>

# Source URL backlinks — the page a file links to on chat context bubbles
divinci rag set-source-url --file-id <fileId> --url https://example.com/page
divinci rag set-source-url --file-id <fileId> --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 <vectorId>
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 <vectorId> --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 <n>`	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

Flag	Description
`--limit <n>`	Max results
`--min-score <f>`	Minimum relevance score (0–1), e.g. `0.7`
`--page <n>`	Page number for file listing
`--status <s>`	Filter files by status: `ready`, `processing`, `error`

`release` — Releases

# List and inspect
divinci release list
divinci release list --status active --limit 10
divinci release get <releaseId>

# Create — blank, or fork an existing release
divinci release create --name "My Release"
divinci release create --name "Arena variant" --from <releaseId> --assistant-id <toolId>

# 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 <releaseId> --name "Renamed"
divinci release update <releaseId> --require-signed-anonymous-chat
divinci release update <releaseId> --fallback-assistants '[{"id":"...","finetune":false}]'

# Lifecycle
divinci release publish <releaseId>
divinci release delete <releaseId>

# Clone across workspaces
divinci release clone <releaseId> --to-workspace <id> --name "Copy"

Flag	Description
`--status <s>`	(`list`) Filter by status: `active`, `draft`, `archived`
`--limit <n>`	(`list`) Max results
`--name <name>`	(`create`, required) Release name
`--from <releaseId>`	(`create`) Fork an existing release — copies RAG, moderation, prefixes, assistant config
`--assistant-id <toolId>`	(`create --from`) Override the forked release’s AI Model selection
`--url <url>`	(`create-from-mcp`, required) MCP server URL to discover tools from
`--fallback-assistants <json>`	(`update`) Ordered fallback model chain
`--require-signed-anonymous-chat` / `--no-…`	(`update`) Toggle the anonymous-chat HMAC requirement
`--rerank-max-chunks <n>`	(`update`) Cap RAG chunks after merge-rerank
`--ai-gateway` / `--no-ai-gateway`	(`update`) Toggle Cloudflare AI Gateway routing
`--response-cache` / `--response-cache-ttl <s>`	(`update`) Public response cache controls
`--to-workspace <id>`	(`clone`, required) Destination workspace
`--rag-id-map <json>` / `--rag-id-map-file <path>`	(`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.

# Consumer side: check the gate, then accept
divinci terms show <releaseId>
divinci terms accept <releaseId>

# 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 <tosId>
divinci terms update <tosId> --file ./terms-v2.md
divinci terms publish <tosId>

`workspace` — Workspaces

Available via both workspace and the shorter ws alias.

# List available workspaces
divinci workspace list
divinci ws list --limit 50

# Inspect a specific workspace
divinci workspace get <workspaceId>

# Set the default workspace for all subsequent commands
divinci workspace use <workspaceId>

`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.

# 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.

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.

divinci group list
divinci group get <groupId>
divinci group create --name "Engineering"
divinci group update <groupId> --name "Platform Engineering"
divinci group delete <groupId>

# Invite a user to a group
divinci group invite <groupId> --email user@example.com

# Remove a user from a group
divinci group remove-user <groupId> --user <userId>

`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.

# List effective permissions on a resource
divinci permissions list --resource <resourceId>

# Show your own effective permissions
divinci permissions mine

# Grant or revoke a permission
divinci permissions grant --resource <resourceId> --principal <userOrGroupId> --role editor
divinci permissions revoke --resource <resourceId> --principal <userOrGroupId>

`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.

divinci byok list
divinci byok get <credentialId>
divinci byok create --provider openai --key sk-...
divinci byok rotate <credentialId> --key sk-...
divinci byok delete <credentialId>

`api-key` — Workspace API keys

Long-lived workspace tokens for daemons and CI. Creation and rotation print the secret exactly once — store it immediately.

divinci api-key list
divinci api-key create --name "GitHub Actions"
divinci api-key rotate <keyId>
divinci api-key delete <keyId>

# Configure per-key request limits
divinci api-key request-limit <keyId> --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.

# 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 <requestId> --status approved
divinci admin rate-limit-requests decide <requestId> --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.

divinci training-data generate --rag <ragVectorId>
divinci training-data list
divinci training-data status <jobId>
divinci training-data export <jobId> --format jsonl --out ./out.jsonl
divinci training-data export-to-rag <jobId> --rag <ragVectorId>
divinci training-data delete <jobId>

`qa` — Quality assurance test suites

Build, run, and inspect QA test suites against any release. Subdivides into suites (definitions), runs (executions), and tests (cases).

# Suite management
divinci qa suites list
divinci qa suites get <suiteId>
divinci qa suites set-scorers <suiteId> --scorers exactMatch,llmJudge

# Run a suite (single or multi-release)
divinci qa run <suiteId> --release <releaseId>
divinci qa multi-release-run <suiteId> --releases rel_a,rel_b
divinci qa estimate-run <suiteId>                   # dry-run cost estimate
divinci qa arena-run <suiteId> --preset <presetId>  # head-to-head arena style

# Browse run results
divinci qa runs list --suite <suiteId>
divinci qa runs get <runId>
divinci qa runs cancel <runId>

# Test cases
divinci qa tests generate-tests <suiteId> --count 20
divinci qa augment-training-set <suiteId>
divinci qa calibrate <suiteId>

# Train + snapshot helpers
divinci qa train-from-run <runId> --out <trainingDataId>
divinci qa snapshot-rag-group --rag <ragVectorId>
divinci qa backfill-release-snapshots <releaseId>

# Import / export, ratings, winner picks
divinci qa copy-suite-from <sourceSuiteId> --to <targetWorkspaceId>
divinci qa export <suiteId> --out ./suite.json
divinci qa import ./suite.json
divinci qa regenerate <runId>
divinci qa winner-pick <runId> --winner <variant>
divinci qa list-ratings <runId>
divinci qa list-winner-picks <runId>
divinci qa export-edited-responses <runId> --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.

divinci fine-tune list
divinci fine-tune get <jobId>
divinci fine-tune create --base-model <model> --training-data <dataId>
divinci fine-tune start <jobId>
divinci fine-tune status <jobId>
divinci fine-tune cancel <jobId>
divinci fine-tune delete <jobId>

# Cross-feed: fine-tune outputs ↔ QA pipeline
divinci fine-tune export-to-qa <jobId> --suite <suiteId>
divinci fine-tune copy-from <sourceJobId>

`audio` — Audio transcript management

Upload and manage audio assets, then turn transcripts into RAG content.

divinci audio list
divinci audio get <audioId>

# Get a signed upload URL for direct PUT
divinci audio upload-url --content-type audio/mpeg

divinci audio delete <audioId>

# Generate a RAG document from an audio transcript
divinci audio generate-rag <audioId> --rag <ragVectorId>

`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.

# Rules
divinci style-pattern list
divinci style-pattern list-proposed
divinci style-pattern list-edits
divinci style-pattern test-rewrite --text "..." --rule <ruleId>
divinci style-pattern approve <proposedId>
divinci style-pattern reject <proposedId>
divinci style-pattern toggle <ruleId>
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 <runId> --out ./run.jsonl
divinci style-pattern training-run-transition <runId> --to ready

`arena-preset` — Arena preset management

Configure the side-by-side variants used by qa arena-run and the arena UI.

divinci arena-preset list
divinci arena-preset export <presetId> --out ./preset.json
divinci arena-preset clone <sourcePresetId> --to <newName>
divinci arena-preset update-variant <presetId> --variant A --model gpt-4o

`notifications` — Notifications & delivery

Workspace notifications plus delivery channels (email/webhook) and tag-routing triggers. See Observability for the full pipeline.

divinci notifications list --unread
divinci notifications counts
divinci notifications mark-read <notificationId>

# 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 <channelId>   # email channels
divinci notifications channels test <channelId>
divinci notifications channels logs <channelId>     # webhook delivery logs

# Delivery triggers — tag → channel routing
divinci notifications triggers create --title "Escalations" --any-tags urgent --channels <channelId>

`flagger` — Custom notification flaggers

LLM-driven custom notifications: a flagger evaluates chat traffic with your prompt and raises a tagged notification when it flags.

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 <flaggerId> "I want my money back!"   # dry-run (billed)
divinci flagger list
divinci flagger delete <flaggerId>

`feedback` — Message feedback

# List feedback (paginated, filtered)
divinci feedback list
divinci feedback list --release <id> --sentiment negative --has-text

# Aggregate stats (sentiment / source / per-release breakdown)
divinci feedback stats

# Inspect a single record
divinci feedback get <feedbackId>

Flag	Description
`--release <id>`	Filter to one release
`--sentiment <s>`	Filter by sentiment
`--source <s>`	Filter by feedback source
`--has-text`	Only feedback with a text comment
`--created-after <ms>` / `--created-before <ms>`	Time-range filter (epoch ms)
`--page <n>` / `--limit <n>`	Pagination

`analytics` — Product analytics

Metrics, trends, per-product performance, A/B experiments, and the conversion funnel for your AI releases.

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.

divinci metrics pipeline <pipelineId> --time-range 24h
divinci metrics export <pipelineId> --format csv

divinci metrics alerts list <pipelineId>
divinci metrics alerts set <pipelineId> --node-type embedding --metric errorRate \
  --warning 0.05 --critical 0.2 --webhook https://ops.example.com/alert
divinci metrics alerts ack <pipelineId> <alertId>

divinci metrics usage <orgName>        # API-key usage stats
divinci metrics billing-report         # BYOK vs wallet comparison

`trust` — TrustBench (v1 skeletons)

divinci trust benchmarks                # List available benchmark definitions
divinci trust run <benchmarkId>         # Execute a benchmark run (skeleton)
divinci trust list                      # List your recent runs
divinci trust verify <runId>            # Verify a signed run log

Global Options

These flags work with every command:

Option	Description
`--api-key <key>`	Override the API key for this single invocation
`--workspace <id>`	Override the workspace ID
`--profile <name>`	Use a named profile (default: `default`)
`--api-url <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.

# 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 <id> 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.

# ❌ 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 <id> (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:

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:

# 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 <id> to set a default — or pass --workspace <id> 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.

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 <id>.

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 — API key types, token scopes, and best practices
Quick Start — SDK integration alongside the CLI
API Reference — Full REST API documentation

Divinci CLI

Installation

Quick Start

Authentication

Configuration

Environment Variables

Project Config File

Commands Reference

auth — Manage credentials

chat — Conversations

rag — Knowledge Base

release — Releases

terms — Terms of Service

workspace — Workspaces

api — Raw API Requests

config — Workspace configuration

group — User group management

permissions — Permission management

byok — Bring-your-own-key credentials

api-key — Workspace API keys

admin — Platform-admin operations

training-data — Generate training data from RAG

qa — Quality assurance test suites

fine-tune — Fine-tuning lifecycle

audio — Audio transcript management

style-pattern — Per-workspace style rules

arena-preset — Arena preset management

notifications — Notifications & delivery

flagger — Custom notification flaggers

feedback — Message feedback

analytics — Product analytics

metrics — Pipeline telemetry & alerts

trust — TrustBench (v1 skeletons)

Global Options

Scripting & CI/CD

Always pin --workspace in automation

CI/CD Authentication

Multi-Environment Profiles

Troubleshooting

Next Steps

`auth` — Manage credentials

`chat` — Conversations

`rag` — Knowledge Base

`release` — Releases

`terms` — Terms of Service

`workspace` — Workspaces

`api` — Raw API Requests

`config` — Workspace configuration

`group` — User group management

`permissions` — Permission management

`byok` — Bring-your-own-key credentials

`api-key` — Workspace API keys

`admin` — Platform-admin operations

`training-data` — Generate training data from RAG

`qa` — Quality assurance test suites

`fine-tune` — Fine-tuning lifecycle

`audio` — Audio transcript management

`style-pattern` — Per-workspace style rules

`arena-preset` — Arena preset management

`notifications` — Notifications & delivery

`flagger` — Custom notification flaggers

`feedback` — Message feedback

`analytics` — Product analytics

`metrics` — Pipeline telemetry & alerts

`trust` — TrustBench (v1 skeletons)

Always pin `--workspace` in automation