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 --jsonA 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 --jsonCommon 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-subjectsinspect-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:
--inputaccepts CSV, TSV, parquet, JSON, and JSONL;--value-colpicks the column (inferred when there is a single numeric column).--time-colorders rows, rejects duplicate times, and reports sampling ininput.series.time_axis. Gaps or irregular steps addinput.warningsand makequality_statusreview.- For a regular numeric time column, tools with a
sample_rateparameter getsample_rate = 1 / stepunless 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_statusis always set for tool runs:ok, orreviewwhenresult.warningsorinput.warningsare present.- Numeric arrays longer than 16 values are echoed in
input.paramsas{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_changepointstandardizes the series by a robust noise scale, so changepoints do not depend on units. The default cost isnormal, and the default penalty is3·log(n)(2·log(n)forrbf) times(1+ρ)/(1−ρ)for lag-1 autocorrelation ρ. Above 500 samples, candidates usejump = ceil(n/500). The result reports the algorithm that actually ran (method,requested_method) and the effectivesettings.detect_periodicitytests detrended spectral peaks against an AR(1) background and requires an autocorrelation peak at the same lag and at leastmin_cycles(default 3) cycles.detected,p_value, andcandidate_perioddescribe the outcome. STL/MSTL/Holt-Winters auto-period use the same test and fail rather than guess.find_discords/find_motifsdefaultexclusion_zonetom; discords carryrobust_z(distance in MAD units from the profile median). Top-k discords always exist, so judge them byrobust_z.analyze_recurrencereports decimation (downsample_step) and returns the matrix only withinclude_matrix=true;analyze_matrix_profilereturns the full profile only withinclude_profile=true.- Classifiers report accuracy, balanced accuracy, macro-F1, and a confusion matrix.
compare_classifiersranks byrank_metric(defaultbalanced_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.jsonForecasting 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 --jsonKey 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 |