The DarkDuck CLI handles instance setup, diagnostics, and control-plane operations.

​
Installation

The CLI is included in the DarkDuck package. Use it via npx or pnpm: 
npx darkduck --help

​
Global Options

All commands support:
FlagDescription
--data-dir <path>Local DarkDuck data root (isolates from ~/.darkduck)
--api-base <url>API base URL
--api-key <token>API authentication token
--context <path>Context file path
--profile <name>Context profile name
--jsonOutput as JSON
Company-scoped commands also accept --company-id <id>.

​
Context Profiles

Store defaults to avoid repeating flags: 
# Set defaults
pnpm darkduck context set --api-base http://localhost:3100 --company-id <id>

# View current context
pnpm darkduck context show

# List profiles
pnpm darkduck context list

# Switch profile
pnpm darkduck context use default
To avoid storing secrets in context files, use an env var reference: 
pnpm darkduck context set --api-key-env-var-name DARKDUCK_API_KEY
export DARKDUCK_API_KEY=...
Context is stored at ~/.darkduck/context.json.
Use separate profiles for different companies or DarkDuck instances. Switch between them with darkduck context use <profile>.

​
Isolated Instances

For clean local instances, pass --data-dir on the command you run: 
pnpm darkduck run --data-dir ./tmp/darkduck-dev
This keeps all data under the specified directory instead of ~/.darkduck.

​
Command Categories

The CLI has two categories:
  1. Setup commands — instance bootstrap, diagnostics, configuration
  2. Control-plane commands — issues, agents, approvals, activity

Setup Commands

Onboard, run, doctor, and configure

Control-Plane Commands

Issue, agent, approval, and dashboard operations