> ## Documentation Index > Fetch the complete documentation index at: https://docs.valkyrie.vals.ai/llms.txt > Use this file to discover all available pages before exploring further. # valkyrie run > Complete generated reference for every `valkyrie run` command. This page documents all 13 commands in the `run` group in registration order. Use the table of contents to jump to a command.

`valkyrie run analyze`

Trigger Docent ingestion + error analysis for a finished run. ```bash Syntax theme={null} valkyrie run analyze \ \ [--no-cache] ``` **Arguments**
{"RUN_ID"}required · {"UUID"}
**Options**
{"--no-cache"}optional · {"boolean"} · default: {"False"}

{"Bypass the cached reading-plan URL and re-fire ingestion."}

Task guidance: [Run guides](/runs/start). ***

`valkyrie run errors`

Show stored run and current task error messages. ```bash Syntax theme={null} valkyrie run errors \ \ [--format ] ``` ```bash Example theme={null} valkyrie run errors 123e4567-e89b-12d3-a456-426614174000 ``` **Arguments**
{"RUN_ID"}required · {"UUID"}
**Options**
{"--format"}optional · {"choice"} · default: {"'text'"} · constraints: {"one of `text`, `json`; case-insensitive"}

{"Output format."}

Task guidance: [Run guides](/runs/start). ***

`valkyrie run fetch`

Fetch a run by its run id. ```bash Syntax theme={null} valkyrie run fetch \ \ [--connect] \ [--format ] ``` ```bash Example theme={null} valkyrie run fetch \ 123e4567-e89b-12d3-a456-426614174000 \ --connect ``` **Arguments**
{"RUN_ID"}required · {"UUID"}
**Options**
{"--connect"}optional · {"boolean"} · default: {"False"}

{"Connect to the tracker service to stream run updates"}

{"--format"}optional · {"choice"} · default: {"'text'"} · constraints: {"one of `text`, `json`, `jsonl`; case-insensitive"}

{"Output format. Use json for a snapshot or jsonl with --connect."}

Task guidance: [Run guides](/runs/start). ***

`valkyrie run list`

List runs by providing filter values. ```bash Syntax theme={null} valkyrie run list \ [--agent-name ] \ [--benchmark-name ] \ [--model ] \ [--dataset ] \ [--label|-l ] \ [--status ] \ [--order-by ] \ [--started-by ] \ [--format ] \ [--all] ``` ```bash Example theme={null} valkyrie run list \ --agent-name claude_code \ --benchmark-name swebench \ --status IN_PROGRESS \ --order-by DESC ``` **Options**
{"--agent-name"}optional · {"text"}

{"Agent name (e.g., claude_code)"}

{"--benchmark-name"}optional · {"text"}

{"Benchmark name (e.g., swebench)"}

{"--model"}optional · {"text"}

{"Model name (e.g., anthropic/claude-sonnet-4-20250514)"}

{"--dataset"}optional · {"text"}

{"Dataset name (e.g., default, terminal-bench-2.1)"}

{"--label, -l"}optional · {"text"}

{"Run label"}

{"--status"}optional · {"choice"} · default: {"None"} · constraints: {"one of `IN_PROGRESS`, `STOPPING`, `STOPPED`, `FINISHED`, `ERROR`; case-insensitive"}

{"Status of the benchmarks to fetch (e.g., in_progress, finished, error)"}

{"--order-by"}optional · {"choice"} · default: {"'desc'"} · constraints: {"one of `asc`, `desc`; case-insensitive"}

{"Order by the benchmarks to fetch (e.g., desc, asc)"}

{"--started-by"}optional · {"text"} · default: {"None"}

{"Comma-separated list of starter emails (e.g., alice@example.com,bob@example.com). Case-insensitive."}

{"--format"}optional · {"choice"} · default: {"'text'"} · constraints: {"one of `text`, `json`; case-insensitive"}

{"Output format. Machine-readable JSON requires --all."}

{"--all"}optional · {"boolean"} · default: {"False"}

{"Fetch every matching run without interactive paging. Requires --format json."}

Task guidance: [Run guides](/runs/start). ***

`valkyrie run output`

Download files from a benchmark run by its ID. ```bash Syntax theme={null} valkyrie run output \ \ [] \ [-o|--output-dir ] ``` **Arguments**
{"BENCHMARK_ID"}required · {"UUID"}
{"SUBPATH"}optional · {"text"} · default: {"''"}
**Options**
{"-o, --output-dir"}optional · {"path"} · default: {"None"} · constraints: {"readable"}

{"Directory to save downloaded files (defaults to ./)"}

Task guidance: [Run guides](/runs/start). ***

`valkyrie run outputs`

Fetch run outputs by run id. ```bash Syntax theme={null} valkyrie run outputs \ \ [--output-dir ] \ [--task-ids ] ``` ```bash Example theme={null} valkyrie run outputs \ 123e4567-e89b-12d3-a456-426614174000 \ --output-dir ./run_outputs ``` **Arguments**
{"RUN_ID"}required · {"UUID"}
**Options**
{"--output-dir"}optional · {"path"} · default: {"None"} · constraints: {"readable"}

{"Directory to save run outputs (defaults to ./__)"}

{"--task-ids"}optional · {"text"} · default: {"None"}

{"Comma-separated list of task IDs to download (e.g., astropy__astropy-7606,django__django-10880)"}

Task guidance: [Run guides](/runs/start). ***

`valkyrie run results`

Retrieve run results by its run id. ```bash Syntax theme={null} valkyrie run results \ \ [--path ] \ [--s3] \ [--task-ids ] \ [--task-ids-file ] ``` ```bash Example theme={null} valkyrie run results \ 123e4567-e89b-12d3-a456-426614174000 \ --path ./results-123e4567-e89b-12d3-a456-426614174000.json ``` **Arguments**
{"RUN_ID"}required · {"UUID"}
**Options**
{"--path"}optional · {"path"} · default: {"None"} · constraints: {"file; readable"}

{"Path to save the results (default: ./results-.json)"}

{"--s3"}optional · {"boolean"} · default: {"False"}

{"Saves results to s3 instead of downloading them locally. Can be found at bucket://benchmarks/run_id/.json"}

{"--task-ids"}optional · {"text"} · default: {"None"}

{"Comma-separated task IDs to score the subset over. Final score is recomputed over the subset."}

{"--task-ids-file"}optional · {"text"} · default: {"None"}

{"Path or http(s) URL to a text file with one task ID per line"}

Task guidance: [Run guides](/runs/start). ***

`valkyrie run resume`

Resume a run by its run id. ```bash Syntax theme={null} valkyrie run resume \ \ [--retry] \ [--concurrency ] \ [--task-ids ] \ [--task-ids-file ] \ [--secret|-s ...] \ [--update-agent|-u] \ [--from-scratch] \ [--benchmark-url ] \ [--connect] ``` ```bash Example theme={null} # Example only — review before running valkyrie run resume \ 123e4567-e89b-12d3-a456-426614174000 \ --retry \ --concurrency 20 ``` **Arguments**
{"RUN_ID"}required · {"UUID"}
**Options**
{"--retry"}optional · {"boolean"} · default: {"False"}

{"Retry tasks with the status error"}

{"--concurrency"}optional · {"integer"} · default: {"None"} · constraints: {">= 1"}

{"Override concurrency level (e.g., 20)"}

{"--task-ids"}optional · {"text"} · default: {"None"}

{"Comma-separated list of task IDs (e.g., astropy__astropy-12907,astropy__astropy-12908)"}

{"--task-ids-file"}optional · {"text"} · default: {"None"}

{"Path or http(s) URL to a text file with one task ID per line"}

{"--secret, -s"}optional · {"tuple[text, text]"} · constraints: {"2 values; repeatable"}

{"Secret as ENV_VAR aws_secret_name (e.g., -s ANTHROPIC_API_KEY AnthropicApiKey)"}

{"--update-agent, -u"}optional · {"boolean"} · default: {"False"}

{"Refresh the frozen agent copy from the current agents/.zip in S3 before resuming."}

{"--from-scratch"}optional · {"boolean"} · default: {"False"}

{"Clear durable eval state and rerun generation."}

{"--benchmark-url"}optional · {"text"} · default: {"None"}

{"Replace the benchmark service URL for this run."}

{"--connect"}optional · {"boolean"} · default: {"False"}

{"Connect to the tracker service to stream run updates after resuming"}

Task guidance: [Run guides](/runs/start). ***

`valkyrie run retry`

Retry a run's errored tasks by its run id. ```bash Syntax theme={null} valkyrie run retry \ \ [--concurrency ] \ [--task-ids ] \ [--task-ids-file ] \ [--secret|-s ...] \ [--update-agent|-u] \ [--from-scratch] \ [--benchmark-url ] \ [--connect] ``` ```bash Example theme={null} # Example only — review before running valkyrie run retry \ 123e4567-e89b-12d3-a456-426614174000 \ --concurrency 20 ``` `retry` is a command alias for the retry mode of `run resume` and shares its options. It always retries tasks in `ERROR` status; use `run resume` to admit pending tasks instead. **Arguments**
{"RUN_ID"}required · {"UUID"}
**Options**
{"--concurrency"}optional · {"integer"} · default: {"None"} · constraints: {">= 1"}

{"Override concurrency level (e.g., 20)"}

{"--task-ids"}optional · {"text"} · default: {"None"}

{"Comma-separated list of task IDs (e.g., astropy__astropy-12907,astropy__astropy-12908)"}

{"--task-ids-file"}optional · {"text"} · default: {"None"}

{"Path or http(s) URL to a text file with one task ID per line"}

{"--secret, -s"}optional · {"tuple[text, text]"} · constraints: {"2 values; repeatable"}

{"Secret as ENV_VAR aws_secret_name (e.g., -s ANTHROPIC_API_KEY AnthropicApiKey)"}

{"--update-agent, -u"}optional · {"boolean"} · default: {"False"}

{"Refresh the frozen agent copy from the current agents/.zip in S3 before resuming."}

{"--from-scratch"}optional · {"boolean"} · default: {"False"}

{"Clear durable eval state and rerun generation."}

{"--benchmark-url"}optional · {"text"} · default: {"None"}

{"Replace the benchmark service URL for this run."}

{"--connect"}optional · {"boolean"} · default: {"False"}

{"Connect to the tracker service to stream run updates after resuming"}

Task guidance: [Run guides](/runs/start). ***

`valkyrie run start`

Start a run. ```bash Syntax theme={null} valkyrie run start \ --agent \ [--model ] \ --benchmark \ [--concurrency ] \ [--lambda ] \ [--task-ids ] \ [--task-ids-file ] \ [--slice ] \ [--dataset ] \ [--provider ] \ [--label|-l ] \ [--kwarg|-k ...] \ [--secret|-s ...] \ [--header|-H ...] \ [--interval|-i ...] \ [--ignore-custom-services|--ics] \ [--connect] \ [--count|-n ] ``` ```bash Example theme={null} # Example only — review before running valkyrie run start \ --agent agents/claude_code \ --benchmark swebench \ --concurrency 5 ``` **Options**
{"--agent"}required · {"text"}

{"Path to local agent directory or S3 agent name (e.g., agents/claude_code or claude_code)"}

{"--model"}optional · {"text"}

{"Model key (e.g., openai/gpt-4o)"}

{"--benchmark"}required · {"text"}

{"Name of the benchmark to run (e.g., swebench, finance)"}

{"--concurrency"}optional · {"integer"} · default: {"5"} · constraints: {">= 1"}

{"Number of concurrent tasks to run (e.g., 5)"}

{"--lambda"}optional · {"text"} · default: {"None"}

{"Lambda function to invoke at the end of the benchmark run"}

{"--task-ids"}optional · {"text"} · default: {"None"}

{"Comma-separated list of task IDs (e.g., astropy__astropy-12907,astropy__astropy-12908)"}

{"--task-ids-file"}optional · {"text"} · default: {"None"}

{"Path or http(s) URL to a text file with one task ID per line"}

{"--slice"}optional · {"text"} · default: {"None"}

{"Dataset slice in Python slice syntax start:stop[:step] (e.g., 0:10)"}

{"--dataset"}optional · {"text"} · default: {"None"}

{"Dataset name to use from the benchmark service (defaults to 'default')"}

{"--provider"}optional · {"text"} · default: {"None"}

{"Named sandbox provider from config (e.g., daytona, modal)"}

{"--label, -l"}optional · {"text"} · default: {"None"}

{"Label to attach to the run"}

{"--kwarg, -k"}optional · {"tuple[text, text]"} · constraints: {"2 values; repeatable"}

{"Kwargs as key value (e.g., -k temperature 7 -k max_tokens 1000)"}

{"--secret, -s"}optional · {"tuple[text, text]"} · constraints: {"2 values; repeatable"}

{"Secret as ENV_VAR aws_secret_name (e.g., -s ANTHROPIC_API_KEY AnthropicApiKey)"}

{"--header, -H"}optional · {"tuple[text, text]"} · constraints: {"2 values; repeatable"}

{"Custom header for benchmark service requests (e.g., -H Authorization my-credential)"}

{"--interval, -i"}optional · {"integer"} · constraints: {"repeatable"}

{"Progress percentage threshold for Slack notification (e.g., -i 25 -i 75). Max 3, must be divisible by 5, range 5-100."}

{"--ignore-custom-services, --ics"}optional · {"boolean"} · default: {"False"}

{"Ignore custom benchmark services that have been configured. Provides opt-out for custom services."}

{"--connect"}optional · {"boolean"} · default: {"False"}

{"Connect to the tracker service to stream run updates after starting"}

{"--count, -n"}optional · {"integer"} · default: {"1"} · constraints: {">= 1; <= 10"}

{"Number of independent runs to start"}

Task guidance: [Run guides](/runs/start). ***

`valkyrie run status`

Fetch lightweight status for multiple run IDs. ```bash Syntax theme={null} valkyrie run status \ --ids \ [--format ] ``` ```bash Example theme={null} valkyrie run status \ --ids 123e4567-e89b-12d3-a456-426614174000,123e4567-e89b-12d3-a456-426614174001 \ --format json ``` **Options**
{"--ids"}required · {"text"}

{"Comma-separated run UUIDs. Duplicates are ignored while preserving order."}

{"--format"}optional · {"choice"} · default: {"'text'"} · constraints: {"one of `text`, `json`; case-insensitive"}

{"Output format."}

Task guidance: [Run guides](/runs/start). ***

`valkyrie run stop`

Stop a run by its run id. ```bash Syntax theme={null} valkyrie run stop \ \ [--task-ids ] \ [--task-ids-file ] \ [--force] ``` ```bash Example theme={null} # Example only — review before running valkyrie run stop $RUN_ID ``` **Arguments**
{"RUN_ID"}required · {"UUID"}
**Options**
{"--task-ids"}optional · {"text"} · default: {"None"}

{"Comma-separated list of task IDs to stop"}

{"--task-ids-file"}optional · {"text"} · default: {"None"}

{"Path or http(s) URL to a text file with one task ID per line"}

{"--force"}optional · {"boolean"} · default: {"False"}

{"Force stop the benchmark run"}

Task guidance: [Run guides](/runs/start). ***

`valkyrie run update`

Update concurrency for an active run. ```bash Syntax theme={null} valkyrie run update \ \ --concurrency ``` ```bash Example theme={null} # Example only — review before running valkyrie run update \ 123e4567-e89b-12d3-a456-426614174000 \ --concurrency 10 ``` **Arguments**
{"RUN_ID"}required · {"UUID"}
**Options**
{"--concurrency"}required · {"integer"} · constraints: {">= 1"}

{"New maximum number of concurrent tasks"}

Task guidance: [Run guides](/runs/start).