Skip to main content

CLI Quick Reference

Practical patterns for the ts-agents CLI. Not exhaustive, but centered on the workflow/tool grammar that external agents should use.

Install notes: - ts-agents: workflow discovery, inspect-series, and forecast-series --methods seasonal_naive - ts-agents[recommended]: full forecasting comparisons plus activity-recognition - ts-agents[patterns]: change-points, discords/motifs, FLUSS (matrix profile) - ts-agents[ml] / ts-agents[neural]: global GBM / NHITS models for forecast-panel - ts-agents[foundation]: Darts zero-shot foundation models (chronos2_small, chronos2, timesfm2p5, patchtst_fm) for forecast-series, forecast-panel and foundation-smoke - source checkout + uv sync: same base CLI-first profile as ts-agents - source checkout + uv sync --extra recommended: same recommended profile as ts-agents[recommended]

Bundled data

# Run IDs / variables in the bundled smoke fixture used by --run-id/--variable
# workflow inputs (short_real.csv holds only 5 samples per run)
uv run ts-agents data list

# Export the bundled M4 mini-panel for panel forecasting
uv run ts-agents data export-panel m4-monthly-mini --split train --out panel.csv --json

A source checkout also ships data/synthetic_signals.csv: 3000 samples at 50 Hz (t in seconds) with known answers — periodic (2 Hz sine), regime (mean shift at sample 1000, variance tripled at 2000), and anomaly (oscillation flatlined at samples 1500–1529). See data/README.md.

Tool discovery

# Find tools by task words (synonyms such as anomaly, outlier, regime, spectrum)
uv run ts-agents tool search anomaly --json
uv run ts-agents tool search regime --json

# All registered tools
uv run ts-agents tool list

# Tools in a specific bundle
uv run ts-agents tool list --bundle minimal
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 (one entry point per task family), standard, full, all, orchestrator, and one bundle per category.

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

# Task-neutral diagnostics: sampling/gaps, significance-tested periodicity,
# regime screen, and next steps across task families
uv run ts-agents workflow run inspect-series \
  --input data/synthetic_signals.csv --time-col t --value-col periodic \
  --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

# Export the bundled M4 mini-panel (train split; synthetic month-start dates)
uv run ts-agents data export-panel m4-monthly-mini --split train --out panel.csv --json

# Panel forecasting with the base-install seasonal baseline
uv run ts-agents workflow show forecast-panel --json
uv run ts-agents workflow run forecast-panel \
  --input panel.csv --freq MS --horizon 18 --season-length 12 \
  --methods seasonal_naive --skip-plots --output-dir outputs/panel-baseline

# Add a zero-shot foundation model (requires the foundation extra; downloads
# only the chronos2_small checkpoint into HF_HOME on first use)
uv run ts-agents workflow run forecast-panel \
  --input panel.csv --freq MS --horizon 18 --season-length 12 \
  --methods seasonal_naive,chronos2_small --context-length 512 \
  --skip-plots --output-dir outputs/panel-fm

# Zero-shot foundation model on a single series
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,chronos2_small --accelerator cpu \
  --output-dir outputs/forecast-fm

# 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

# Leave-subject-out evaluation for streams that concatenate subjects/sessions
uv run ts-agents workflow run activity-recognition \
  --input data/wisdm_subset.csv --label-col label --group-col subject_id \
  --output-dir outputs/activity-subjects

inspect-series reports result.data.time_axis (median step, regular, gap_count, reordered) and sets quality_flags such as irregular_sampling and periodicity_not_assessed. A series with fewer than 16 samples is degraded because periodicity cannot be assessed. A constant after detrending (such as a pure linear ramp) also has periodicity.assessed: false and a warning. Diagnostic warnings reach the CLI, summary, and report. periodicity.detected is false when no period passes the test; candidate_period shows the strongest candidate when one was assessed.

activity-recognition holds out whole --group-col groups (or, without it, whole label segments) before selecting the window size on the remaining data, and reports the held-out score. eval.json includes details.chance_balanced_accuracy. The held-out fraction may exceed --test-size to retain at least two test classes with training support. --balance and --max-windows-per-segment apply to final training windows; the held-out windows retain their original distribution. Changing group assignments or the group column invalidates --resume. Windows never span groups, and with --labeling majority training windows that share samples with test windows are purged. forecast-series flags irregular_sampling when the time column has gaps.

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

Forecast evaluation requires finite targets, complete finite predictions, and finite MAE/RMSE. An undefined MAPE at zero targets is reported separately and does not invalidate those primary metrics. Numeric time coordinates remain numeric; calendar forecast timestamps are included only when their frequency can be established. Numeric coordinates require exactly equal positive steps; floating-point roundoff can conservatively cause timestamps to be omitted.

Running tools directly

Use ts-agents tool run <tool> to call any individual tool from the command line. For tools with a series parameter, --input loads it from a file:

  • --input accepts CSV, TSV, parquet, JSON, and JSONL; --value-col picks the column (inferred when there is a single numeric column).
  • --time-col orders rows, rejects duplicate times, and reports sampling in input.series.time_axis. Gaps or irregular steps add input.warnings and make quality_status review.
  • For a regular numeric time column, tools with a sample_rate parameter get sample_rate = 1 / step unless you pass one (input.series.sample_rate_source). Periods and frequencies are then in time-column units. Datetime axes stay in samples.
  • Univariate tools reject multichannel arrays, non-finite values, and inputs too short for the method with ok: false; they never flatten channels or return an empty answer for a failed computation.
  • quality_status is always set for tool runs: ok, or review when result.warnings or input.warnings are present.
  • Numeric arrays longer than 16 values are echoed in input.params as {summary, shape, dtype, sha256, head, tail} instead of raw values. Ragged or object sequences are summarized recursively; long sequences use {summary, length, sha256, head, tail}. These summaries describe inputs; the tool still receives their full values.

Method-specific contracts:

  • segment_changepoint standardizes the series by a robust noise scale, so changepoints do not depend on units. The default cost is normal, and the default penalty is 3·log(n) (2·log(n) for rbf) times (1+ρ)/(1−ρ) for lag-1 autocorrelation ρ. Above 500 samples, candidates use jump = ceil(n/500). The result reports the algorithm that actually ran (method, requested_method) and the effective settings.
  • detect_periodicity tests detrended spectral peaks against an AR(1) background and requires an autocorrelation peak at the same lag and at least min_cycles (default 3) cycles. detected, p_value, and candidate_period describe the outcome. STL/MSTL/Holt-Winters auto-period use the same test and fail rather than guess.
  • find_discords/find_motifs default exclusion_zone to m; discords carry robust_z (distance in MAD units from the profile median). Top-k discords always exist, so judge them by robust_z.
  • analyze_recurrence reports decimation (downsample_step) and returns the matrix only with include_matrix=true; analyze_matrix_profile returns the full profile only with include_profile=true.
  • Classifiers report accuracy, balanced accuracy, macro-F1, and a confusion matrix. compare_classifiers ranks by rank_metric (default balanced_accuracy), and unknown ROCKET variants are rejected.

Classification comparisons retain the requested and actual method plus fallback warnings. A missing optional classifier can use a documented fallback, but its score is not evidence that the requested classifier ran. If no classifier can produce predictions, the call fails. hivecote_classify exposes time_limit_in_minutes (default: 1); set it explicitly with --param when a different model-fitting budget is authorized.

# Significant periodicity in time units (2 Hz sine → period 0.5 s)
uv run ts-agents tool run detect_periodicity \
  --input data/synthetic_signals.csv --time-col t --value-col periodic --json

# Change-points (expect ~1000 and ~2000)
uv run ts-agents tool run segment_changepoint \
  --input data/synthetic_signals.csv --value-col regime --json

# Discords (the flatlined segment starts near 1500)
uv run ts-agents tool run find_discords \
  --input data/synthetic_signals.csv --value-col anomaly --param m=100 --json

# STL decomposition with an explicit period
uv run ts-agents tool run stl_decompose \
  --input data/synthetic_signals.csv --value-col periodic --param period=25 --json

# Theta forecast with a custom horizon
uv run ts-agents tool run forecast_theta \
  --input data/synthetic_signals.csv --value-col periodic --param horizon=25 --json

# Two aligned series for coherence (no `series` parameter, so use JSON)
uv run ts-agents tool run compute_coherence \
  --input-json '{"series1":[0,1,0,-1,0,1,0,-1],"series2":[1,0,-1,0,1,0,-1,0]}' --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

Forecasting tools for agents (all VERY_HIGH cost):

# Zero-shot foundation-model point forecast (foundation extra; default model chronos2_small).
# VERY_HIGH cost tools need --approve, otherwise they fail with permission_denied (exit 7).
uv run ts-agents tool show forecast_foundation --json
uv run ts-agents tool run forecast_foundation \
  --input data/synthetic_signals.csv --value-col periodic \
  --param horizon=12 --param model=chronos2_small --approve --json

# Run the forecast-panel workflow from a long-format file; output_dir defaults
# under TS_AGENTS_TOOL_ARTIFACT_DIR
uv run ts-agents tool show forecast_panel_from_csv --json

Key flags:

Flag Purpose
--input File supplying the series parameter
--value-col / --time-col Columns for --input
--input-json / --stdin JSON object of parameters
--param key=value Tool parameter (repeatable)
--json JSON output
--approve Approve very-high-cost tools

Saving output and legacy image extraction

--json emits one response envelope. Requested saving and image extraction must finish before success is printed; if either fails, the command returns only the error envelope and a nonzero exit code.

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. Tools return data rather than plots; --save records the exact envelope:

uv run ts-agents tool run stl_decompose \
  --input data/synthetic_signals.csv --value-col periodic --param period=25 \
  --json --save outputs/stl.json

--extract-images only unwraps legacy [IMAGE_DATA:...] tokens from older saved outputs. Use workflow run ... --output-dir ... when you want PNG, CSV, and report artifacts.

Execution quality and input ordering

Single-series inputs with time coordinates are sorted chronologically together with their values; time_axis.reordered records when that happened. Duplicate, missing, or invalid times and multiple IDs are rejected. Numeric coordinates keep their own units (they are not reinterpreted as dates); results report periods, windows, and indices in samples unless sample_rate was derived from a regular numeric time column. Bare arrays retain row order. Select one series explicitly or use forecast-panel for multiple series.

Ensembles reject empty, unknown, or missing requested members and incomplete or nonfinite forecasts. Legacy comparisons retain their MAE ranking; workflows retain their documented RMSE ranking.

Autoresearch dry runs return result.status: planned and quality_status: planned; no model was fitted or scored. foundation-gpu-plan returns plan-only. Nonfinite primary scores fail the trial and cannot enter a ranking. If no trials succeed, the command fails and retains trial artifacts and a failed manifest. Undefined secondary MAPE includes an explanation.

Opted-in backend fallback records requested/actual backends and sets requires_review; ToolPayload results carry a backend_fallback quality flag. Raw algorithm results retain their original shape; their CLIEnvelope.execution or Python ExecutionResult.metadata carries fallback_used and backend names. Deterministic validation errors are not retryable with unchanged inputs.

Built-in agent run, UI/hosted entrypoints, and LLM report generation were removed in 0.4.0. The run/demo aliases and the bundled-data *_with_data tools were removed in 0.4.1; use tool run <tool> --input <file> and workflow run.

Sandbox modes

Control where tool code executes with --sandbox:

# Default — in-process, no isolation
uv run ts-agents tool run stl_decompose \
  --input data/synthetic_signals.csv --value-col periodic --param period=25

# Separate Python process (the file is read on the host; values are passed in)
uv run ts-agents tool run stl_decompose \
  --input data/synthetic_signals.csv --value-col periodic --param period=25 \
  --sandbox subprocess

# Docker container (requires: ./build_docker_sandbox.sh)
uv run ts-agents tool run stl_decompose \
  --input data/synthetic_signals.csv --value-col periodic --param period=25 \
  --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.

Removed in 0.4.1

Removed Use instead
ts-agents run <tool> ts-agents tool run <tool>
ts-agents demo ... bash demo/run_demo*.sh (source checkout) or workflow run ...
tool run <x>_with_data --run R --var V tool run <x> --input file --value-col V [--time-col t]
demo, demo_windowing, demo_forecasting bundles minimal, standard, full, or a category bundle