┌─────────────────────────────────────────────────────────────┐
│  Rust Launcher (karate binary)                              │
│  - Management commands: setup, update, config, doctor       │
│  - Delegates runtime commands to JVM                        │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼ delegates
┌─────────────────────────────────────────────────────────────┐
│  Java CLI (karate-core Main.java)                           │
│  - Runtime commands: run, mock, mcp, init, clean            │
│  - Receives args from Rust launcher                         │
│  - Uses PicoCLI for parsing                                 │
└─────────────────────────────────────────────────────────────┘

karate <command> [options] [args]

Runtime Commands (implemented in Java):
  run              Run Karate tests
  mock             Start mock server
  mcp              MCP server commands
  clean            Clean output directories

Management Commands (implemented in Rust):
  setup            First-run wizard
  update           Check for updates
  config           View/edit configuration
  init             Initialize new project (interactive)
  doctor           System diagnostics
  version          Show version info

karate run [options] [paths...]

# Run feature files
karate run tests/users.feature

# Run JS scripts
karate run tests/setup.karate.js

# Run mixed (discovers both .feature and .karate.js)
karate run tests/

# Run multiple paths from different packages in a single run
# (useful when positional args are awkward, e.g. via -Dkarate.options in Maven)
karate run -P classpath:com/comp/commission -P classpath:com/comp/statement

# Comma-separated form — tight for Maven: -Dkarate.options="--path a,b"
karate run --path classpath:com/comp/commission,classpath:com/comp/statement

# Run scenario at line 10
karate run tests/users.feature:10

# Run multiple scenarios (lines 10 and 25)
karate run tests/users.feature:10:25

# Works with classpath resources too
karate run classpath:features/users.feature:10

# Run a single scenario by name
karate run -n "Login happy path" tests/users.feature

# The name filter scans all features in the run, so it works across a directory
karate run -n "Login happy path" tests/

# Combine with :LINE to narrow to one row of a Scenario Outline
karate run -n "Parameterized check" tests/outline.feature:9

# Enable Cucumber JSON (HTML still on by default)
karate run -f cucumber:json features/

# Enable multiple formats
karate run -f cucumber:json,junit:xml features/

# Disable HTML, enable Cucumber JSON
karate run -f ~html,cucumber:json features/

# Only JSONL output (disable HTML)
karate run -f ~html,karate:jsonl features/

// karate-config.js — applies to all scenarios in this run
configure logging = {
  mask: {
    headers:    ['Authorization', 'Cookie', 'X-Api-Key'],
    jsonPaths:  ['$.password', '$..token'],
    patterns:   [{ regex: '\\bBearer [A-Za-z0-9._-]+\\b', replacement: 'Bearer ***' }],
    replacement: '***',
    enableForUri: function(uri) { return uri.indexOf('/health') < 0 }
  }
}

# Run with auto-detected karate-pom.json
karate run

# Run specific paths (inherits env, threads, etc. from pom)
karate run src/test/features

# Run with explicit pom file
karate run --pom my-project.json

# Run ignoring karate-pom.json
karate run --no-pom src/test/features

# Run with options
karate run -t @smoke -e dev -T 5 src/test/features

# Run from different working directory
karate run -w /home/user/project src/test/features

{
  "paths": ["src/test/features/", "classpath:features/"],
  "tags": ["@smoke", "~@slow"],
  "env": "dev",
  "threads": 5,
  "scenarioName": "Login happy path",
  "configDir": "src/test/resources",
  "workingDir": "/home/user/project",
  "dryRun": false,
  "clean": false,
  "output": {
    "dir": "target/karate-reports",
    "html": true,
    "junitXml": false,
    "cucumberJson": false,
    "jsonLines": false
  },
  "logging": {
    "report": "debug",
    "console": "info"
  },
  "listeners": ["com.example.MyListener"],
  "listenerFactories": ["com.example.MyListenerFactory"]
}

{
  "workingDir": "/home/user/project/src/test/java",
  "output": {
    "dir": "/home/user/project/target/karate-reports"
  }
}

CLI flags → karate-pom.json → defaults

# Override a Runner class's hard-coded tags from Maven
mvn test -Dtest=MyKarateTest -Dkarate.options="--tags @smoke"

# Multiple overrides in one string
mvn test -Dtest=MyKarateTest -Dkarate.options="--tags @smoke --env qa --threads 4"

# Maven user override using individual env sysprop (terse)
mvn test -Dtest=MyKarateTest -Dkarate.env=qa

# Non-Java team using the standalone CLI with env var
KARATE_OPTIONS="--tags @smoke" karate run features/
KARATE_ENV=qa karate run features/

karate.options (sysprop)
  └─ KARATE_OPTIONS (env)            # only if sysprop absent
    └─ individual sysprops (karate.env, karate.config.dir)
      └─ KARATE_ENV / KARATE_CONFIG_DIR (env)   # fallback
        └─ karate.output.dir
          └─ Runner.Builder values (programmatic)
            └─ karate-pom.json
              └─ defaults

mvn test -Dtest=UsersTest '-Dkarate.options=-P "src/features/happy path" -P "src/features/edge cases"'

@Command(
    name = "karate",
    subcommands = {
        RunCommand.class,
        CleanCommand.class,
    }
)
public class Main implements Callable<Integer> {

    @Parameters(arity = "0..*", hidden = true)
    List<String> unknownArgs;

    @Override
    public Integer call() {
        // No subcommand specified
        if (unknownArgs != null && !unknownArgs.isEmpty()) {
            // Legacy: treat args as paths, delegate to run
            return new RunCommand().runWithPaths(unknownArgs);
        }
        // Look for karate-pom.json in cwd
        if (Files.exists(Path.of("karate-pom.json"))) {
            return new RunCommand().call();
        }
        // Show help
        CommandLine.usage(this, System.out);
        return 0;
    }
}

@Command(name = "run", description = "Run Karate tests")
public class RunCommand implements Callable<Integer> {

    public static final String DEFAULT_POM_FILE = "karate-pom.json";

    @Parameters(description = "Feature files or directories", arity = "0..*")
    List<String> paths;

    @Option(names = {"-p", "--pom"}, description = "Project file (default: karate-pom.json)")
    String pomFile;

    @Option(names = {"--no-pom"}, description = "Ignore karate-pom.json")
    boolean noPom;

    // ... other options ...

    @Override
    public Integer call() {
        // Load pom if present (unless --no-pom)
        if (!noPom) {
            loadPom();
        }
        // CLI args override pom values
        // ... rest of execution
    }
}

@Command(name = "clean", description = "Clean output directories")
public class CleanCommand implements Callable<Integer> {

    @Option(names = {"-o", "--output"}, description = "Output directory to clean")
    String outputDir;

    @Override
    public Integer call() {
        // Cleans:
        // - karate-reports/
        // - karate-reports_*/ (backup directories)
        // - karate-temp/ (Chrome user data, callSingle cache, etc.)
        return 0;
    }
}

target/                          (or build/ for Gradle)
├── karate-reports/              # Test reports (HTML, JSON, etc.)
├── karate-reports_20260125_*/   # Backup directories (when backupReportDir enabled)
└── karate-temp/                 # Runtime temp files (cleaned by 'karate clean')
    ├── chrome-abc12345/         # Chrome/browser user data directories
    └── cache/                   # callSingle disk cache files

karate run src/test/features -t @smoke
    │
    ▼ Rust launcher
java -jar ~/.karate/dist/karate-2.0.0.jar run src/test/features -t @smoke
    │
    ▼ Java CLI
Main.java parses and executes

karate --cp /path/to/karate-ide-v2.jar run features/
karate --cp /path/to/a.jar --cp /path/to/b.jar run features/

{
  "jvm_opts": "-Xmx512m"
}

karate mock --port 8080 mocks/

karate mcp --stdio

karate perf --users 10 --duration 30s features/

// io.karatelabs.cli.CommandProvider
public interface CommandProvider {
    String getName();           // e.g., "perf"
    String getDescription();    // e.g., "Run performance tests"
    Object getCommand();        // PicoCLI command instance
}

ServiceLoader<CommandProvider> providers = ServiceLoader.load(CommandProvider.class);
for (CommandProvider provider : providers) {
    spec.addSubcommand(provider.getName(), provider.getCommand());
}

io.karatelabs/
├── Main.java              # Parent command, delegates to subcommands
└── cli/
    ├── RunCommand.java    # karate run
    └── CleanCommand.java  # karate clean

io.karatelabs.core/
├── KaratePom.java         # JSON pom parsing
├── Runner.java            # Programmatic API
└── ...

# Standard build
mvn clean install -DskipTests

# Build fatjar (for simpler testing)
mvn clean package -DskipTests -Pfatjar

home/test-project/
├── karate-pom.json       # Project file
└── features/
    └── hello.feature     # Test feature with @smoke, @api tags

# Help
./etc/test-cli.sh --help

# Run tests
./etc/test-cli.sh home/test-project/features

# Run with workdir
./etc/test-cli.sh -w home/test-project features

# Run with explicit pom
./etc/test-cli.sh -p home/test-project/karate-pom.json

# Build fatjar first
mvn package -DskipTests -Pfatjar

# Run
java -jar karate-core/target/karate.jar --help
java -jar karate-core/target/karate.jar home/test-project/features

cd karate-core
mvn exec:java -Dexec.mainClass="io.karatelabs.Main" \
  -Dexec.args="--help"

# Build fatjar
mvn package -DskipTests -Pfatjar

# Output: karate-core/target/karate.jar

# Reports generated
ls -la home/test-project/target/reports/

# Expected files
# - karate-summary.html
# - feature-html/*.html (per-feature reports)

rm -rf home/test-project/target