Skip to main content

Dochia CLI Reference

This guide provides a comprehensive reference for all Dochia CLI commands and options.

Overview​

Dochia is a powerful CLI tool for API testing with the following main commands:

  • test - Run systematic API tests
  • fuzz - Continuous fuzzing with random mutators
  • replay - Replay previous test runs
  • list - View available resources
  • explain - Get detailed information about test results
  • info - Show system information

Global Options​

These options are available for all commands:

-h, --help        Show help message and exit
    --help-full   Show full help with all options
    --licenses    Show third-party licenses
-V, --version     Print version information

test​

Run automated API tests against your OpenAPI specification.

Basic Usage​

dochia test -c <contract> -s <server> [options]

Required Arguments​

  • -c, --contract <file> - Path to OpenAPI specification file
  • -s, --server <url> - Base URL of the API server

Common Options​

Test Control​

  • -d, --dry-run - Simulate without making requests
  • -b, --blackbox - Treat only 5XX as errors
  • -A, --headers-only - Test only headers
  • -B, --body-only - Test only request bodies
  • -F, --fields-only - Test only request fields

Output Control​

  • -o, --output <dir> - Output directory (default: dochia-report)
  • --output-format <format> - Output format: HTML_JS (default) or HTML_ONLY
  • --timestamp-reports - Add timestamp to report directory
  • -v - Increase verbosity (can be used multiple times)

Filtering​

  • -p, --paths <paths> - Comma-separated paths to test
  • --skip-paths <paths> - Paths to exclude
  • -X, --http-methods <methods> - HTTP methods to test
  • -P, --playbooks <names> - Specific playbooks to run
  • --skip-playbooks <names> - Playbooks to skip

fuzz​

Run continuous fuzzing with random mutators.

Basic Usage​

dochia fuzz -c <contract> -s <server> -p <path> [options]

Required Arguments​

  • -c, --contract <file> - Path to OpenAPI spec
  • -s, --server <url> - Base URL of API
  • -p, --path <path> - API path to fuzz

Common Options​

  • -X, --http-method <method> - HTTP method (default: POST)
  • --mc, --match-response-codes <codes> - Match specific status codes
  • --se, --stop-after-errors <count> - Stop after N errors
  • --st, --stop-after-time <seconds> - Run for specified duration
  • --sm, --stop-after-mutations <count> - Stop after N mutations

replay​

Replay previously executed tests.

Basic Usage​

dochia replay <test-id> [options]

Arguments​

  • <test-id> - Test ID or path to test file

Options​

  • -s, --server <url> - Override server URL
  • -o, --output <dir> - Save updated test results
  • -H, --header <name=value> - Add/override headers
  • -v - Verbose output

list​

List available resources.

Usage​

dochia list [options]

Options​

  • -p, --paths - List API paths (requires -c)
  • -f, --playbooks - List available playbooks
  • -m, --mutators - List available mutators
  • --cmt, --custom-mutator-types - List custom mutator types
  • -s, --fields-playbook-strategies - List field fuzzing strategies
  • --formats - List supported OpenAPI formats
  • -c, --contract <file> - OpenAPI spec file (for path listing)
  • -j, --json - Output in JSON format

explain​

Explain test results, playbooks, or error codes.

Usage​

dochia explain -t <type> <value>

Arguments​

  • -t, --type <type> - Type to explain: playbook, mutator, response_code, error_reason
  • <value> - Value to explain (e.g., playbook name, status code)

info​

Display system and environment information.

Usage​

dochia info

Exit Codes​

  • 0 - Success
  • 191 - Usage error (invalid arguments)
  • 192 - Internal error
  • N - Number of test errors (for test/fuzz commands)

Examples​

Run Basic Test​

dochia test -c api.yaml -s http://localhost:8080

Fuzz an Endpoint​

dochia fuzz -c api.yaml -s http://localhost:8080 -p /users -X POST

Replay a Test​

dochia replay Test1 -s http://staging.example.com

List Available Playbooks​

dochia list --playbooks

Dochia CLI Reference

This page summarizes Dochia CLI commands and options, based strictly on the official help output in the repository (dochia-cli-*.txt).

Overview​

  • Binary name: dochia
  • Version example: v1.0.2-SNAPSHOT (Free)
  • Global flags:
    • -h, --help Show help and exit
    • --help-full Show full help and exit
    • -V, --version Print version and exit
    • --licenses Show third-party licenses (from root help)

Commands​

  • test Automatically generate and run negative and boundary tests from your OpenAPI spec using 100+ fuzzing playbooks
  • fuzz Run continuous fuzzing based on random mutators (not pre-defined playbooks)
  • replay Replay previously executed Dochia tests
  • list List playbooks, OpenAPI paths, formats, mutators, custom mutator types, and field fuzzing strategies
  • explain Get details about a playbook, mutator, response code, or error reason
  • info Get environment debug info to help in bug reports (see root help)

test​

Usage:

dochia test -c <contract> -s <server> [ADDITIONAL OPTIONS]

Required:

  • -c, --contract <contract> OpenAPI contract/spec
  • -s, --server <server> Base URL of the service

Common options (selected, see help for full list):

  • API

    • --connection-timeout <sec> Default: 10
    • --read-timeout <sec> Default: 10
    • --write-timeout <sec> Default: 10
    • --max-requests-per-minute <max> Default: 10000
    • --user-agent <ua> Default: dochia/1.0.2-SNAPSHOT

  • Authentication & Network

    • -u, --user <user:password> Basic auth
    • --auth-refresh <sec> and --auth-refresh-script <script>
    • --proxy <http(s)://host:port>, --proxy-host <host>, --proxy-port <port>
    • --ssl-keystore <keystore>, --ssl-keystore-password <pwd>, --ssl-key-password <pwd>

  • Configuration files (per-path or global controls)

    • -H, --header <name=value> Global header(s)
    • --headers <file> YAML headers per-path
    • -Q <name=value> Global extra query params
    • --query-params <file> YAML query params per-path
    • -R <name=value> Global reference-data field values
    • --reference-data <file> YAML reference-data per-path
    • --execution-order <file> Explicit path execution order
    • --playbooks-config <file> Properties with per-playbook expected codes
    • -K, --error-keywords <file> Line-based keywords file for error-leak detection (one keyword per line)

  • Filter and selection

    • Include-only: -p, --paths, -t, --tags, -X, --http-methods, --field-types, --field-formats
    • Exclude-only: --skip-paths, --skip-tags, --skip-http-methods, --skip-field-types, --skip-field-formats, --skip-fields, --skip-headers
    • Note: include and corresponding skip options are mutually exclusive within the same category
    • Other: -P, --playbooks (and --skip-playbooks), --skip-deprecated-operations
    • -d, --dry-run (use -j, --json to print dry-run output as JSON)

  • Response handling

    • -b, --blackbox Treat only 5xx as errors (equivalent to --filter-codes 2xx,4xx)
    • Success filters: --filter-codes, --filter-lines, --filter-regex, --filter-size, --filter-words
    • Ignore (still reported): -i, --ignore-codes, --ignore-lines, --ignore-regex, --ignore-size, --ignore-words
    • Disable checks: --ignore-body-validation, --ignore-content-type-check, --ignore-error-leak-check, --ignore-undocumented-codes

  • Processing and generation

    • --[no-]use-examples, --[no-]use-property-examples, --use-request-body-examples, --[no-]use-response-body-examples, --use-schema-examples, --[no-]use-defaults
    • --max-schema-combinations <n>, --self-reference-depth <n>, --large-strings-size <n>
    • --fields-selection-strategy <strategy> (Default: ONEBYONE)
    • --max-tested-fields <n>, --max-fields-to-remove <n>
    • --edge-spaces-strategy <strategy> (VALIDATE_AND_TRIM | TRIM_AND_VALIDATE)
    • --sanitization-strategy <strategy> (SANITIZE_AND_VALIDATE | VALIDATE_AND_SANITIZE)
    • --content-type <mime>, --http2-prior-knowledge, --resolve-response-combinations, --rfc7396

  • Reporting and output

    • -o, --output <folder> Default: dochia-report
    • --output-format <format[,format...]> Supported: HTML_JS (default), HTML_ONLY
    • --timestamp-reports
    • Console: --[no-]color, --execution-stats, --detailed-execution-stats, -v (repeatable), --print-progress
    • --mask-headers <header[,header...]>
    • --max-response-time <ms> mark slow responses as error if otherwise successful

Exit codes: 0 success, 191 usage error, 192 internal error, ERR equals number of errors

Examples:

# Blackbox mode, only 5xx as errors
dochia test -c openapi.yml -s http://localhost:8080 -b

# Add auth header from shell var
dochia test -c openapi.yml -s http://localhost:8080 -H API-Token=$TOKEN

fuzz​

Usage:

dochia fuzz [OPTIONS]

Key options (selected):

  • Target

    • -c, --contract <contract>
    • -s, --server <server>
    • -p, --path <path> (single API path)
    • -X, --http-method <method> Default: POST
    • --schema-discriminator <name=value> (filter payloads for oneOf/anyOf)
    • --content-type <mime>

  • Auth/Network: same as test (proxy, SSL keystore, basic auth, refresh script)

  • Files

    • --headers <file>, -H <name=value>
    • --query-params <file>, -Q <name=value>
    • --reference-data <file>, -R <name=value>
    • --playbooks-config <file>
    • --error-keywords <file> (line-based)
    • -M, --mutators <folder> (for dochia fuzz)

  • Match and stop criteria

    • Match: --mc <codes>, --mi, --ml <lines>, --mr <regex>, --ms <sizes>, --mw <words>
    • Stop: --se <max-errors>, --sm <max-mutations>, --st <seconds>

  • Reporting and output: same family as test (HTML_JS, HTML_ONLY, -o, --timestamp-reports, --execution-stats, -v, etc.)

Exit codes: same as test

Examples:

# Fuzz one path with POST for 100s, treat 500 as error
 dochia fuzz -X POST -p /my-path -s http://localhost:8080 \
   --mc 500 --st 100 -H header=value

replay​

Usage:

dochia replay [OPTIONS] <tests>[,<tests>...]...

Arguments:

  • <tests> List of test IDs or file paths. If it ends with .json, it is treated as a path; otherwise it searches in the default report folder.

Options (selected):

  • -s, --server <server> Override base URL used during original run
  • -H <name=value> Override/append headers for replay
  • -o, --output <folder> Write updated TestXXX.json files to a folder
  • Auth/Network: --auth-refresh, --auth-refresh-script, proxy, SSL keystore, -u basic auth
  • -v verbose, -V version

Exit codes: same as test

Examples:

# Replay Test1 from default reporting folder
dochia replay Test1

# Replay Test1 and output refreshed results to a different folder
dochia replay Test1 --output path/to/new/folder

list​

Usage:

dochia list [-hjV] [--help-full] ([-p [--path=<path>] [--tag=<tag>] -c=<contract>] | -f | [[-m] [--cmt]] | [-s] | [formats])

Modes:

  • OpenAPI paths: --paths -c <contract>, with optional --path <path>, --tag <tag>
  • Playbooks: --playbooks
  • Mutators: --mutators, custom mutator types: --customMutatorTypes
  • Field Fuzzing Strategies: --fieldsPlaybookStrategies
  • Formats supported by generators: --formats

Flags: -j, --json (JSON console output), standard help/version flags

Examples:

# List all paths for an OpenAPI contract
dochia list --paths -c openapi.yml

# List all available playbooks
dochia list --playbooks

explain​

Usage:

dochia explain -t <type> <info>

Description: Get details about a playbook, mutator, response code, or error reason.

Options:

  • -t, --type <type> One of: playbook, mutator, response_code, error_reason
  • Standard help/version flags

Examples:

# Explain a response code
dochia explain --type response_code 953

# Explain an error reason
dochia explain --type error_reason "Error details leak"

info​

Description: Print environment debug info to help in bug reports (see root help).

Usage:

dochia info

Exit codes​

  • 0 Success
  • 191 Usage error (invalid user input)
  • 192 Internal execution error
  • ERR Number of errors reported by Dochia (for test/fuzz runs)