CLI Quick Reference

Practical patterns for the ts-agents CLI. Not exhaustive, but centered on the current workflow/tool grammar rather than the deprecated compatibility aliases.

Install notes: - ts-agents: workflow discovery, inspect-series, and forecast-series --methods seasonal_naive - ts-agents[recommended] or uv sync: full forecasting comparisons plus activity-recognition

Data discovery

# List all available runs and variables
uv run ts-agents data list

# Only run IDs
uv run ts-agents data list --runs

# Only variable names
uv run ts-agents data list --variables

# Use the full dataset instead of the test subset
uv run ts-agents data list --full-data

Tool discovery

# All registered tools
uv run ts-agents tool list

# Tools in a specific bundle
uv run ts-agents tool list --bundle demo
uv run ts-agents tool list --bundle standard

# Tools in a category
uv run ts-agents tool list --category forecasting
uv run ts-agents tool list --category classification

# Filter by cost
uv run ts-agents tool list --max-cost medium

# JSON output
uv run ts-agents tool list --category forecasting --json

Common bundles: minimal (5 tools), standard (15), full (25+), demo, demo_windowing, demo_forecasting.

Workflow discovery and execution

# Environment-aware overview of workflows, tools, extras, and sandboxes
uv run ts-agents capabilities --json

# List first-class workflows
uv run ts-agents workflow list
uv run ts-agents workflow list --json
uv run ts-agents workflow show forecast-series --json

# Inspect a short series
uv run ts-agents workflow run inspect-series \
  --input-json '{"series":[1,2,3,4,5,6,7,8,9,10]}' \
  --output-dir outputs/inspect

# Forecast a deterministic inline series with the base-install baseline
uv run ts-agents workflow run forecast-series \
  --input-json '{"series":[1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20]}' \
  --horizon 5 \
  --methods seasonal_naive \
  --output-dir outputs/forecast

# Run labeled-stream activity recognition (requires classification/recommended extras)
uv run python data/make_synthetic_labeled_stream.py \
  --scenario gait --seconds 40 --seed 1337 \
  --out data/demo_labeled_stream.csv
uv run ts-agents workflow run activity-recognition \
  --input data/demo_labeled_stream.csv \
  --label-col label \
  --value-cols x,y,z \
  --output-dir outputs/activity

If you omit --output-dir, workflows create a unique run directory under outputs/<workflow>/ and write run_manifest.json plus the generated artifacts there.

Running tools directly

Use ts-agents tool run <tool> to call any individual tool from the command line.

# STL decomposition
uv run ts-agents tool run stl_decompose_with_data \
  --run Re200Rm200 --var bx001_real

# Theta forecast with a custom horizon
uv run ts-agents tool run forecast_theta_with_data \
  --run Re200Rm200 --var bx001_real \
  --param horizon=30 \
  --json

# Window-size selection with multiple params
uv run ts-agents tool run select_window_size_from_csv \
  --param csv_path=data/demo_labeled_stream.csv \
  --param value_columns=x,y,z \
  --param label_column=label \
  --param window_sizes=32,64,96,128,160 \
  --param metric=balanced_accuracy \
  --param classifier=minirocket \
  --json \
  --save outputs/demo/window_selection.json

Key flags:

Flag	Purpose
`--run`	Run ID
`--var`	Variable name
`--param key=value`	Tool parameter (repeatable)
`--json`	JSON output
`--approve`	Approve very-high-cost tools

Saving output and legacy image extraction

Workflow commands already write artifact files under --output-dir, or to an auto-generated run directory when you omit that flag. Read run_manifest.json inside the workflow output directory to enumerate the generated artifacts. Use the lower-level tool run path below when you want a machine-readable record of a specific plot-producing tool response:

uv run ts-agents tool run stl_decompose_with_data \
  --run Re200Rm200 --var bx001_real \
  --json \
  --save outputs/Re200Rm200/stl.json

Read the saved tool JSON and use result.artifacts[*].path for the generated PNG paths. --extract-images only unwraps legacy [IMAGE_DATA:...] tokens from older compatibility outputs. Forecasting forecast_*_with_data wrappers no longer embed plots; treat them as structured numeric compatibility tools. Use workflow run forecast-series --output-dir ... when you want forecast PNG/CSV/report artifacts.

Agent mode

# Simple agent (single-turn, fast)
uv run ts-agents agent run "Find peaks in bx001_real for Re200Rm200"

# Deep agent (multi-step orchestrator)
uv run ts-agents agent run --type deep \
  "Compare forecasting methods for bx001_real"

# Restrict to a tool bundle
uv run ts-agents agent run --type simple --tool-bundle demo \
  "Run the windowing demo workflow"

# Deep agent with auto-approval
uv run ts-agents agent run --type deep --approval auto \
  "Compare forecasting methods for bx001_real"

Flag	Default	Options
`--type`	`simple`	`simple`, `deep`
`--tool-bundle`	`standard`	Any bundle name
`--approval`	`off`	`off`, `auto`, `prompt`

Sandbox modes

Control where tool code executes with --sandbox:

# Default — in-process, no isolation
uv run ts-agents tool run stl_decompose_with_data --run Re200Rm200 --var bx001_real

# Separate Python process
uv run ts-agents tool run stl_decompose_with_data --run Re200Rm200 --var bx001_real \
  --sandbox subprocess

# Docker container (requires: ./build_docker_sandbox.sh)
uv run ts-agents tool run stl_decompose_with_data --run Re200Rm200 --var bx001_real \
  --sandbox docker

Mode	Isolation	Requirements
`local`	None (in-process)	None
`subprocess`	Separate process	None
`docker`	Container	Docker + `./build_docker_sandbox.sh`
`daytona`	Cloud sandbox	`pip install daytona` + `DAYTONA_API_KEY` (optional overrides: `TS_AGENTS_DAYTONA_SNAPSHOT`, `TS_AGENTS_DAYTONA_STREAM`, `TS_AGENTS_DAYTONA_LOG_FILE`)
`modal`	Serverless cloud	Source-checkout deploy path: `pip install modal` + `modal token new` (opens browser) or `MODAL_TOKEN_ID`/`MODAL_TOKEN_SECRET`; from the repo root deploy with `modal deploy -m ts_agents.sandbox.modal_app --env main --name ts-agents-sandbox`; optional stream/file flags: `TS_AGENTS_MODAL_STREAM`, `TS_AGENTS_MODAL_LOG_FILE`

You can also set the default via the TS_AGENTS_SANDBOX_MODE environment variable.

Compatibility note

ts-agents run ... and ts-agents demo ... still work for one release cycle to avoid breaking existing scripts, but both surfaces now emit deprecation warnings. Use tool run and workflow run in new automation and docs.