CLI Overview The warp-md CLI is designed for AI agents first . Every command returns structured JSON output with stable exit codes, making it easy to integrate into automated workflows.
Command Structure warp-md provides three types of commands:
warp-md < comman d > [options] # Utility commands warp-md run < confi g > # Config-based batch analysis warp-md < analysi s > --topology --traj ... # Single analysis commands
JSON Envelope Contract All analysis commands (both run and single-analysis) emit JSON envelopes to stdout with a stable structure:
Success Envelope { "schema_version" : "warp-md.agent.v1" , "status" : "ok" , "exit_code" : 0 , "run_id" : "example-run" , "output_dir" : "outputs" , "system" : { "path" : "topology.pdb" }, "trajectory" : { "path" : "traj.xtc" }, "analysis_count" : 2 , "started_at" : "2026-03-03T10:00:00Z" , "finished_at" : "2026-03-03T10:05:30Z" , "elapsed_ms" : 330000 , "warnings" : [], "results" : [ { "analysis" : "rg" , "out" : "outputs/rg.npz" , "status" : "ok" , "device" : "cuda:0" , "chunk_frames" : 500 , "timing_ms" : 1234 , "artifact" : { "path" : "outputs/rg.npz" , "format" : "npz" , "size_bytes" : 4096 } } ] }
Error Envelope { "schema_version" : "warp-md.agent.v1" , "status" : "error" , "exit_code" : 3 , "run_id" : null , "output_dir" : null , "system" : null , "trajectory" : null , "analysis_count" : 0 , "started_at" : "2026-03-03T10:00:00Z" , "finished_at" : "2026-03-03T10:00:01Z" , "elapsed_ms" : 1000 , "warnings" : [], "results" : [], "error" : { "code" : "E_ANALYSIS_SPEC" , "message" : "rdf.sel_a selection is required" , "context" : { "analysis" : "rdf" , "index" : 0 }, "details" : [ { "type" : "value_error" , "field" : "analyses.0.sel_a" , "message" : "rdf.sel_a selection is required" } ] } }
Schema version identifier (currently warp-md.agent.v1)
Execution status: ok, dry_run, or error
Exit code (0 = success, 2 = config validation, 3 = analysis spec, 4 = runtime, 5 = internal)
Array of completed analysis results with output paths and metadata
Error details (only present when status is error)
Exit Codes Code Name Meaning 0 _EXIT_OKSuccess 2 _EXIT_CONFIG_VALIDATIONConfig file validation failed 3 _EXIT_ANALYSIS_SPECAnalysis specification error 4 _EXIT_RUNTIME_EXECRuntime execution error 5 _EXIT_INTERNALInternal error
Error Codes Code Exit Code Meaning E_CONFIG_LOAD2 Failed to load config file E_CONFIG_VALIDATION2 Config validation failed (schema mismatch) E_ANALYSIS_UNKNOWN3 Unknown analysis name E_ANALYSIS_SPEC3 Invalid analysis parameters E_SYSTEM_LOAD4 Failed to load topology/system E_TRAJECTORY_LOAD4 Failed to load trajectory E_RUNTIME_EXEC4 Analysis execution failed E_OUTPUT_DIR4 Failed to create output directory E_ATLAS_FETCH4 ATLAS download failed E_INTERNAL5 Internal/unexpected error
warp-md config files can be JSON or YAML:
Minimal Config { "version" : "warp-md.agent.v1" , "system" : { "path" : "topology.pdb" }, "trajectory" : { "path" : "traj.xtc" }, "output_dir" : "outputs" , "analyses" : [ { "name" : "rg" , "selection" : "protein" } ] }
Full Config { "version" : "warp-md.agent.v1" , "run_id" : "prod-run-001" , "system" : { "path" : "system.pdb" , "format" : "pdb" }, "trajectory" : { "path" : "traj.xtc" , "format" : "xtc" , "length_scale" : 10.0 }, "device" : "cuda:0" , "chunk_frames" : 500 , "stream" : "ndjson" , "output_dir" : "outputs" , "analyses" : [ { "name" : "rg" , "selection" : "protein" , "mass_weighted" : false , "out" : "outputs/rg.npz" }, { "name" : "rmsd" , "selection" : "backbone" , "reference" : "topology" , "align" : true , "device" : "cpu" , "chunk_frames" : 1000 } ] }
Schema version (use warp-md.agent.v1)
Optional run identifier for tracking
Topology file path or {path, format} object
Trajectory file path or {path, format, length_scale} object
Compute device: auto, cpu, cuda, or cuda:0
Default frames per processing chunk
Streaming mode: none or ndjson
Directory for output files
List of analysis specifications
Streaming Mode (NDJSON) When --stream ndjson is enabled, warp-md emits real-time progress events to stdout (one JSON object per line):
warp-md run config.json --stream ndjson
Event Types run_started { "event" : "run_started" , "run_id" : "example" , "analysis_count" : 3 , "completed" : 0 , "total" : 3 , "progress_pct" : 0.0 }
analysis_started { "event" : "analysis_started" , "index" : 0 , "analysis" : "rg" , "out" : "outputs/rg.npz" }
analysis_completed { "event" : "analysis_completed" , "index" : 0 , "analysis" : "rg" , "status" : "ok" , "timing_ms" : 1234 , "progress_pct" : 33.333 , "eta_ms" : 2468 }
run_completed { "event" : "run_completed" , "final_envelope" : { ... }}
run_failed / analysis_failed { "event" : "run_failed" , "final_envelope" : { "status" : "error" , ... }}
Discovery Commands Discovery commands help agents introspect available analyses and schemas:
# List available analyses warp-md list-plans warp-md list-plans --json warp-md list-plans --format json --details # Show config schema warp-md schema --kind request warp-md schema --kind result warp-md schema --kind event # Generate example config warp-md example # List water models warp-md water-models --json
Usage Examples Single Analysis warp-md rg --topology protein.pdb --traj traj.xtc --selection "protein" --out rg.npz
Output:
{ "status" : "ok" , "exit_code" : 0 , "results" : [{ "analysis" : "rg" , "out" : "rg.npz" , "status" : "ok" }] }
Batch Analysis with Streaming warp-md run config.json --stream ndjson 2> progress.log
Stderr receives NDJSON events, stdout receives final envelope.
Dry Run warp-md run config.json --dry-run
Validates config and shows what would run without executing analyses.
Debug Mode warp-md rg --topology top.pdb --traj traj.xtc --selection "invalid" --debug-errors
Includes Python traceback in error envelope for debugging.
warp-md Command Reference Complete reference for all warp-md commands and analysis types
warp-pack Reference Molecule packing utility reference
warp-pep Reference Peptide builder and mutation tool reference