CLI Reference

Complete reference for all dokkimi CLI commands.

Commands overview

Command	Description
`dokkimi init`	Scaffold a `.dokkimi/` folder with example files
`dokkimi validate [path]`	Validate definition files without running
`dokkimi run [target]`	Run definition(s) and stream live results
`dokkimi inspect [path]`	Interactively inspect results from the last run
`dokkimi dump [path]`	Output raw JSON data dump for debugging
`dokkimi doctor`	Run environment pre-flight checks
`dokkimi status`	Show service and instance status
`dokkimi clean`	Stop all instances and clean up resources
`dokkimi telemetry [on\|off]`	Show or change anonymous telemetry preference
`dokkimi version`	Show installed version

dokkimi run

Resolves definitions, submits them, and streams live status. Exits with code 0 if all pass, 1 if any fail.

Target argument

The target is flexible, similar to Jest:

# Path-based targets
dokkimi run                          # .dokkimi/ in cwd (or nearest parent)
dokkimi run /path/to/project         # Finds /path/to/project/.dokkimi/
dokkimi run .dokkimi/                # Explicit .dokkimi/ directory
dokkimi run .dokkimi/auth-tests      # Only definitions in that subfolder
dokkimi run .dokkimi/auth.json       # A specific definition file

# Pattern-based targets (matches file names/paths within .dokkimi/)
dokkimi run auth                     # Substring match
dokkimi run "auth/**"                # Glob pattern
dokkimi run "auth.*service"          # Regex pattern

Watch mode

dokkimi run --watch
dokkimi run auth --watch

Watches .dokkimi/**/*.{json,yml,yaml} for changes (500ms debounce).

Keyboard controls:

r — re-run all
f — re-run failed only
i — inspect results (available after run completes)
q — quit

Post-run inspect prompt

After a run completes (TTY only, non-watch), the CLI prompts: Press i to inspect results, or any other key to exit.... In CI/non-TTY environments, this is skipped.

dokkimi inspect

Full-screen interactive TUI for drilling into test results and traffic logs. Uses the terminal's alternate screen buffer.

Navigation

Arrow keys + Enter to navigate menus
ESC or q to go back
Ctrl+C to exit

Per-definition drill-down

Raw Definition — opens the definition JSON in your editor
Test Logs — timestamps, events, errors
Items — item status and console logs per service/database/mock
Test Steps — drill into each step group and individual step

Per-step detail view

Raw Step Definition
Test Logs (scoped to the step's group)
Assertions (pass/fail with expected vs actual)
Variables (before/after the step)
HTTP Traffic (inter-service calls during the step)
DB Queries (database operations during the step)
Console Logs (per-service stdout/stderr during the step)

Selecting a log item opens it as a temp file in your $EDITOR (defaults to code).

dokkimi dump

Outputs a complete JSON data dump of the last run — designed for piping to LLMs or scripts.

dokkimi dump                             # Output to stdout
dokkimi dump -o run-dump.json            # Write to file (streams, low memory)
dokkimi dump --failed -o failures.json   # Only failed instances
dokkimi dump .dokkimi/auth.json -o out.json  # Specific definitions only

Options

Option	Description
`-o, --output <file>`	Write to file instead of stdout (streams instance-by-instance)
`--failed`	Only include instances that failed
`[path]`	Filter to definitions matching a file or folder

Output structure

{
  "runId": "...",
  "status": "COMPLETED|FAILED",
  "createdAt": "...",
  "completedAt": "...",
  "instances": [
    {
      "name": "definition-name",
      "status": "...",
      "testStatus": "PASSED|FAILED|null",
      "errorMessage": "...|null",
      "definition": { ... },
      "items": [ ... ],
      "testExecutionLogs": [ ... ],
      "assertionResults": [ ... ],
      "httpLogs": [ ... ],
      "databaseLogs": [ ... ],
      "consoleLogs": [ ... ]
    }
  ]
}

dokkimi doctor

Checks your environment is ready to run tests:

Node.js version (20+ required)
Docker daemon is running
Kubernetes cluster is reachable
Cluster has sufficient resources
Dokkimi internal components are deployed

Each check reports pass, warn, or fail with a fix suggestion.

dokkimi validate

dokkimi validate                  # Validate all definitions
dokkimi validate .dokkimi/auth.json  # Validate a specific file

Checks that all $ref paths resolve, schemas are valid, and naming rules are followed — without deploying anything.

Other commands

dokkimi init

Scaffolds a .dokkimi/ folder with example definitions, shared fragments, and init scripts.

dokkimi status

Shows the current state of Dokkimi services and any running test instances.

dokkimi clean

Stops all running instances, destroys their namespaces, and cleans up cluster resources.

dokkimi telemetry

dokkimi telemetry        # Show current preference
dokkimi telemetry on     # Enable anonymous telemetry
dokkimi telemetry off    # Disable telemetry

dokkimi version

Prints the installed version (e.g., v0.1.0).

← Assertions