CLI Reference

Complete reference for all dokkimi CLI commands.

Commands overview

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)
• b — review baselines (shown when visual baselines are pending)
• 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 test and individual step

Per-step detail view

• Raw Step Definition
• Test Logs (scoped to the step)
• 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 baselines

Interactive TUI for reviewing and approving pending visual baselines from the last run. Uses the alternate screen buffer.

When a test definition includes screenshot sub-steps with match: true, Dokkimi compares captures against baselines stored in .dokkimi/<project>/baselines/. New captures (no baseline yet) and failed diffs appear as pending baselines.

Navigation

Three-level drill-down: tests → baselines → detail.

• Arrow keys + Enter to navigate
• y / a ��� approve a baseline (writes the file immediately)
• s — skip a baseline (marks as skipped, no file written)
• o / → / Enter — open images in your editor (detail view)
• A — approve all baselines at the current level
• ESC / q / ← to go back

Approved baselines are written to .dokkimi/<project>/baselines/. Commit the changes to git so they travel with the test definitions.

Also accessible via the b key after a run completes (when pending baselines are detected).

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

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 config

Interactive settings editor. Opens a full-screen menu with three categories:

• Concurrency — max parallel namespaces and max booting namespaces
• Kubernetes context — select which context Dokkimi uses from your kubeconfig file
• Telemetry — enable or disable anonymous usage telemetry

Settings are saved to ~/.dokkimi/config.json. After making changes, you can reboot Dokkimi services immediately or exit with a reminder to run dokkimi reboot.

dokkimi version

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