Skip to content

dry-run#

Generate parameters and print the command without executing.

Synopsis#

oxo-call dry-run [OPTIONS] <TOOL> <TASK>
oxo-call d       [OPTIONS] <TOOL> <TASK>

Options#

Option Description
-m, --model <MODEL> Override the LLM model for this invocation
--no-cache Skip cached documentation and fetch fresh --help output
--json Output result as JSON (useful for scripting and CI)
--optimize-task Before generating the command, use LLM to expand and refine the task description
-V, --var KEY=VALUE Substitute {KEY} in the task description before the LLM call (repeatable)
-i, --input-list <FILE> Read input items from a file; shows the command for each item
--input-items <ITEMS> Comma-separated input items; shows the command for each item
-v, --verbose Show docs source, skill info, and LLM details (global)
--license <PATH> Path to license file (global option)

Description#

dry-run follows the same pipeline as run (documentation fetch → skill loading → LLM generation) but prints the resulting command instead of executing it. Use this to:

  • Preview commands before running them
  • Verify oxo-call understands your intent
  • Generate commands to copy into scripts
  • Test with tools that aren't installed locally
  • Produce JSON output for pipeline integration
  • Preview batch command expansions before a real run

Examples#

# Preview a samtools command
oxo-call dry-run samtools "view only primary alignments from file.bam"
# → samtools view -F 0x904 file.bam

# Preview a complex alignment
oxo-call d bwa "align paired reads R1.fq R2.fq to hg38.fa using 16 threads"
# → bwa mem -t 16 hg38.fa R1.fq R2.fq

# Use a specific model
oxo-call dry-run --model gpt-4 gatk "call variants on sample.bam"

# Get JSON output for scripting
oxo-call dry-run --json samtools "flagstat input.bam"

# Force fresh documentation
oxo-call dry-run --no-cache samtools "sort input.bam"

# Expand a vague task before generating
oxo-call dry-run --optimize-task samtools "sort bam"

# Variable substitution — preview with {SAMPLE} replaced
oxo-call dry-run --var SAMPLE=NA12878 samtools \
    "sort {SAMPLE}.bam by coordinate"

# Preview all batch commands that would run
oxo-call dry-run samtools "flagstat {item}" \
    --input-items s1.bam,s2.bam,s3.bam

# Preview from a file list
oxo-call dry-run samtools "sort {item} by coordinate, output {stem}.sorted.bam" \
    --input-list bam_files.txt

Task Optimization (--optimize-task)#

When --optimize-task is set, an extra LLM call refines the task description before command generation. The optimized task is shown when it differs from the original, and is used as the actual prompt for the LLM.

Batch Preview (--input-list / --input-items)#

When input items are provided, dry-run calls the LLM once to generate a command template, then prints the interpolated command for each item without executing any of them. This lets you verify the expansion before committing to a real batch run.

Supported placeholders in the task / generated command:

Placeholder Expands to
{item} / {line} The current input item
{nr} 1-based item number
{basename} Filename without directory
{dir} Directory portion (or .)
{stem} Filename without last extension
{ext} File extension without dot

JSON Output#

When --json is used for a single-item dry-run, the output is a JSON object:

{
  "tool": "samtools",
  "task": "flagstat input.bam",
  "effective_task": "flagstat input.bam",
  "command": "samtools flagstat input.bam",
  "args": ["flagstat", "input.bam"],
  "explanation": "Generates alignment statistics for the BAM file",
  "dry_run": true,
  "skill": "samtools",
  "model": "gpt-4o"
}

For batch dry-run (--input-list / --input-items) with --json:

{
  "tool": "samtools",
  "task_template": "flagstat {item}",
  "command_template": "samtools flagstat {item}",
  "commands": [
    "samtools flagstat s1.bam",
    "samtools flagstat s2.bam"
  ],
  "dry_run": true,
  "skill": "samtools",
  "model": "gpt-4o"
}