Add --cp flag for external classpath contributions

Allow extensions and plugins to inject proprietary JARs into
the JVM classpath via a global --cp flag on delegated commands.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: ptrthomas

docs/spec.md

@@ -167,15 +167,27 @@ Everything else passes through to the JVM:
   * Delegated to Karate JAR
   * Launcher constructs JVM command:
     * JRE path
-    * Classpath (fatjar + plugins + ext/*.jar)
+    * Classpath (fatjar + ext/*.jar + --cp entries)
     * JVM opts from config
 
-### **E. Extensions Support**
+### **E. Extensions & Classpath**
 
 * **User extensions:** `~/.karate/ext/` — manually dropped JARs, always added to classpath
+* **`--cp` flag:** Additional classpath entries appended after ext JARs. Can be specified multiple times. Useful for IDE integrations and proprietary JARs.
 * For v1, extensions are managed manually by dropping JAR files into the `ext/` folder
 * Future versions may add managed plugin installation via manifest
 
+**Classpath order:** karate fatjar → `~/.karate/ext/*.jar` → `.karate/ext/*.jar` → `--cp` entries
+
+**Example:**
+```bash
+# Add a proprietary debug adapter JAR
+karate --cp /path/to/karate-ide-v2.jar run features/
+
+# Multiple extra JARs
+karate --cp /path/to/a.jar --cp /path/to/b.jar run features/
+```
+
 ### **F. Config Management**
 
 * Global: `~/.karate/karate-cli.json`
@@ -240,7 +252,11 @@ Everything else passes through to the JVM:
 ## **5.1 Command Overview**
 
 ```text
-karate <command> [options]
+karate [global-options] <command> [options]
+
+Global Options:
+  --no-color             Disable colored output
+  --cp <path>            Additional classpath entry (repeatable)
 
 Management Commands (Rust-native):
   setup [subcommand]     First-run wizard or targeted setup

src/cli.rs

@@ -12,6 +12,11 @@ pub struct Cli {
     #[arg(long, global = true, env = "NO_COLOR")]
     pub no_color: bool,
 
+    /// Additional classpath entries (JAR files or directories) appended to the JVM classpath.
+    /// Can be specified multiple times. Only applies to JAR-delegated commands.
+    #[arg(long = "cp", global = true, num_args = 1)]
+    pub extra_classpath: Vec<String>,
+
     #[command(subcommand)]
     pub command: Command,
 }

src/delegate.rs

@@ -9,7 +9,7 @@ use std::path::{Path, PathBuf};
 use std::process::Command;
 
 /// Run a delegated command through the JVM.
-pub async fn run(args: Vec<String>) -> Result<ExitCode> {
+pub async fn run(args: Vec<String>, extra_classpath: &[String]) -> Result<ExitCode> {
     let paths = KaratePaths::new();
     let config = load_merged_config()?;
 
@@ -30,7 +30,7 @@ pub async fn run(args: Vec<String>) -> Result<ExitCode> {
     let jar_path = find_karate_jar(&dist_dir)?;
 
     // Build classpath
-    let classpath = build_classpath(&paths, &jar_path)?;
+    let classpath = build_classpath(&paths, &jar_path, extra_classpath)?;
 
     // Build JVM command
     let mut cmd = Command::new(&java_executable);
@@ -112,7 +112,12 @@ fn find_karate_jar(dist_dir: &Path) -> Result<PathBuf> {
 }
 
 /// Build the classpath string.
-fn build_classpath(paths: &KaratePaths, jar_path: &Path) -> Result<String> {
+/// Order: karate jar → ext jars (global + local) → extra classpath (--cp flags)
+fn build_classpath(
+    paths: &KaratePaths,
+    jar_path: &Path,
+    extra_classpath: &[String],
+) -> Result<String> {
     let mut classpath_parts = vec![jar_path.to_string_lossy().to_string()];
 
     // Add extensions from both global and local ext directories
@@ -128,6 +133,11 @@ fn build_classpath(paths: &KaratePaths, jar_path: &Path) -> Result<String> {
         }
     }
 
+    // Add extra classpath entries from --cp flags
+    for entry in extra_classpath {
+        classpath_parts.push(entry.clone());
+    }
+
     // Join with platform-appropriate separator
     let separator = if cfg!(windows) { ";" } else { ":" };
     Ok(classpath_parts.join(separator))

src/main.rs

@@ -45,7 +45,7 @@ async fn run() -> ExitCode {
         Command::Version(args) => commands::version::run(args).await,
 
         // JAR-delegated commands
-        Command::External(args) => delegate::run(args).await,
+        Command::External(args) => delegate::run(args, &cli.extra_classpath).await,
     };
 
     match result {