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

Run flags

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 junit

Generates a JUnit XML report from a test run. Useful for CI integration and test result aggregation.

dokkimi junit                              # Output XML to stdout
dokkimi junit -o results.xml               # Write to file
dokkimi junit --failed -o failures.xml     # Only failed instances
dokkimi junit --summary                    # Markdown summary instead of XML

Options

GitHub Actions integration

Generate XML during the run with --junit, then produce a Markdown summary for the GitHub Step Summary:

- name: Run tests
  run: dokkimi run .dokkimi/ --ci --junit junit-results.xml

- name: Post summary
  if: always()
  run: dokkimi junit --summary --dir . >> $GITHUB_STEP_SUMMARY

See CI Pipeline for complete workflow examples.

dokkimi doctor

Checks your environment is ready to run tests:

• Node.js version (20+ required)
• Docker daemon is running
• Docker 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 stop

Stops the current test run without cleaning up resources or history. If no run is active, reports that there is nothing to stop.

dokkimi status

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

dokkimi clean

Stops all running instances, removes their Docker networks and containers, and cleans up resources. Use --all to clean across all projects.

dokkimi reboot

Restarts all Dokkimi services (shuts down then re-starts). Use after changing configuration with dokkimi config.

dokkimi shutdown

Stops all running Dokkimi services without restarting them.

dokkimi config

Interactive settings editor. Opens a full-screen menu with categories for concurrency (max parallel environments, max booting environments) and telemetry. Settings are saved to ~/.dokkimi/config.json.

dokkimi mcp

Starts the MCP server in stdio mode for AI tool integration. This is registered automatically on install for Claude Code, Cursor, and Copilot — you typically only need this command to manually restart the server if it stops responding.

dokkimi uninstall

Fully removes Dokkimi: stops services, removes Docker containers/networks/images, deletes ~/.dokkimi/, and removes AI tool configuration entries.

dokkimi version

Prints the installed version.