CLI Commands

Every routeframe command, flag, and example. Run routeframe <command> --help for inline usage at any time.

routeframe run

routeframe run <model> [flags]

Load a model and forecast from values passed directly on the command line. Good for quick checks and scripting.

$ routeframe run toto --input "45,48,52,49,55,58,62,67" --horizon 4
Model:   Toto (toto)
Input:   8 timesteps, 1 variate
Horizon: 4 steps

Predictions:
  t+1: 68.4200
  t+2: 71.0500
  t+3: 69.8800
  t+4: 72.3100

Flags

Flag	Default	Description
--input	required	Comma-separated time series values.
--horizon	1	Number of future steps to predict.
--format	text	Output format: `text`, `json`, `csv`.
--exogenous-future	—	Known future covariate values. Semicolon-separated variates, comma-separated values: `"0,1,0;72,75,68"`.
--chart	false	Render an ASCII chart of historical data + forecast in the terminal.
--backend	ggml	`ggml` (default, Metal/CUDA) or `pytorch` (exact PyTorch parity).
--no-gpu	false	Disable GPU acceleration, run on CPU only.
--threads	0 (auto)	Number of CPU threads.

Output formats

# JSON
$ routeframe run toto --input "10,12,11,14" --horizon 2 --format json
{
  "model": "toto",
  "horizon": 2,
  "mean": [14.82, 15.31]
}

# CSV — pipe-friendly
$ routeframe run toto --input "10,12,11,14" --horizon 2 --format csv
step,prediction
1,14.8200
2,15.3100

routeframe forecast

routeframe forecast [file] [flags]

Load time series from a file or URL and forecast all specified columns. Supports CSV, Parquet, Arrow, DuckDB, SQLite, and HTTP/HTTPS URLs. Drag a file into the terminal to paste its path.

# CSV — auto-detects numeric columns
$ routeframe forecast data.csv --model toto --horizon 8
SERIES    t+1       t+2       t+3       ...   LATENCY
--------  -------   -------   -------         -------
sales     241.98    276.88    268.14    ...   4ms
revenue   2419.80   2768.73   2681.38   ...   3ms

# Remote URL
$ routeframe forecast https://example.com/metrics.parquet --column cpu_usage

# DuckDB table
$ routeframe forecast warehouse.duckdb --table orders --column revenue --horizon 24

# Multiple columns, exogenous variables, JSON output
$ routeframe forecast data.csv \
    --columns "sales,units" \
    --exogenous "holidays" \
    --model toto --horizon 12 \
    --format json --output results.json

# Discover columns before forecasting
$ routeframe forecast data.csv --list-columns
COLUMN   TYPE    NOTE
date     object  ← timestamp (auto-detected)
sales    int64
revenue  int64

64 rows · frequency: D

Flags

Flag	Short	Default	Description
--file	-f	required	File path or URL. Or pass as positional argument.
--column	-c	—	Single target column to forecast.
--columns	—	all numeric	Multiple target columns (comma-separated).
--exogenous	-x	—	Known future covariate column names (comma-separated). Future values are taken from the tail of the file.
--model	-m	toto	Model: `toto`, `timesfm`, `chronos2`.
--horizon	-n	8	Prediction horizon in steps.
--timestamp	-t	auto	Timestamp column name (auto-detected from common names).
--table	—	—	Table name for DuckDB or SQLite sources.
--format	—	table	Output format: `table`, `csv`, `json`.
--output	-o	stdout	Write results to a file.
--list-columns	—	false	Print available columns and exit without forecasting.
--no-gpu	—	false	Disable GPU acceleration.
--threads	—	0 (auto)	CPU threads.

routeframe auto

routeframe auto [file] [flags]

Auto-select the best forecasting model for your data. Probes every locally-pulled foundation model on a held-out portion of the data, ranks them with bootstrap 95% CIs, compares against daily and weekly seasonal naive baselines, and prints a recommendation.

Designed to collapse the "which model should I use, and is fine-tuning worth it?" question into a single 5-10 second command. Reuses the same data loader as routeframe forecast, so it works with CSV, Parquet, Arrow/Feather, DuckDB, SQLite, and HTTP/HTTPS URLs.

$ routeframe auto data.csv --column sales --horizon 24

# Or just drag a file into the terminal
$ routeframe auto warehouse.duckdb --table orders --column revenue

Example output

┃ Auto-select foundation model for "vehicles"
┃ 5556 observations · frequency: h · horizon: 12
┃ Daily seasonal lag: 24 steps · Weekly seasonal lag: 168 steps
┃ Probing 4 candidate model(s): TimesFM 2.5 Toto Chronos-Bolt Chronos 2
┃ Holdout windows: 1111 total, evaluating up to 100

Stage 1: cheap rank on 20 windows (drop bottom half)...
  ✓ TimesFM 2.5    MAE    120  (459ms)
  ✓ Toto           MAE   1056  (489ms)
  ✓ Chronos-Bolt   MAE    354  (502ms)
  ✓ Chronos 2      MAE    214  (478ms)

Stage 2: full evaluation on 100 windows with bootstrap CIs...
  ✓ TimesFM 2.5    MAE    120 [113, 127]  (461ms)
  ✓ Chronos 2      MAE    198 [186, 211]  (481ms)
  ✓ Daily naive    MAE    341 [323, 359]  (baseline)
  ✓ Weekly naive   MAE    180 [171, 189]  (baseline)

Ranked results
RANK  MODEL         BY        MAE   95% CI
----  -----         --        ---   ------
1     TimesFM 2.5   Google    120   [113, 127]
2     Weekly naive  baseline  180   [171, 189]
3     Chronos 2     Amazon    198   [186, 211]
4     Daily naive   baseline  341   [323, 359]

Recommendation
TimesFM 2.5 (Google)
MAE 120 [113, 127] on 100 held-out windows
  • TimesFM 2.5 (Google) zero-shot beats the strongest naive baseline (Weekly naive) with non-overlapping 95% CIs.
  • Skipping fine-tuning suggestion -- dataset has 5556 observations (< 10k). Empirical risk on small single-series datasets is high; zero-shot is the safer choice.

To use:
  routeframe forecast --file data.csv --column <col> --model timesfm --horizon 12

How it works

Eligibility filter: only locally-pulled models that meet the minimum-context requirement for your data are considered. Run routeframe pull <model> to add candidates.
Two-stage probing: a cheap first pass on 20 holdout windows drops the bottom half of candidates; the survivors get a full evaluation with up to 100 windows and 1,000-sample bootstrap 95% CIs.
Naive baselines: daily-lag and weekly-lag seasonal naives are always included with the same CI methodology. The lag is derived from the loader's detected frequency (hourly, daily, 5-minute, etc.).
Decision rules: if the best foundation model beats the best naive with non-overlapping CIs, it is recommended. If not, the recommendation defaults to the foundation model with a caveat. The fine-tune suggestion is gated on dataset size (skipped under 10,000 observations).

Flags

Flag	Short	Default	Description
--file	-f	—	Data file path or URL. Can also be a positional argument.
--column	-c	—	Target column to forecast. Auto-detected if omitted.
--timestamp	-t	—	Timestamp column. Auto-detected if omitted.
--table	—	—	Table name (DuckDB / SQLite).
--horizon	-n	12	Forecast horizon in steps.
--holdout	—	0.2	Fraction of the data to hold out for evaluation.
--max-windows	—	100	Maximum holdout windows to evaluate in stage 2.
--bootstrap	—	1000	Bootstrap iterations for the 95% CIs.
--seed	—	42	Random seed for window sampling and bootstrap.
--no-stage1	—	false	Skip the cheap first-stage rank and run all candidates through stage 2.
--no-naive	—	false	Skip daily and weekly naive baselines.

routeframe pull

routeframe pull <model> [flags]

Download a model from the registry with a live progress bar and SHA256 verification. With no flags, picks the latest version and smallest parameter count available.

$ routeframe pull toto
Pulling toto  2.0 4m f32  16 MB

  [██████████████████████████████] 16.0 / 16 MB  12.3 MB/s  100%
  SHA256 verified ✓
  Saved to ~/.routeframe/models/toto.gguf  (16 MB)

# See everything available for a model
$ routeframe pull toto --list

# Pin a specific version + parameter count -- doesn't overwrite
# other Toto variants you already have on disk
$ routeframe pull toto --version 2.0 --params 1b
$ routeframe pull toto --version 1.0

# Other models
$ routeframe pull timesfm    # Google TimesFM 2.5  (441 MB)
$ routeframe pull chronos2   # Amazon Chronos 2    (228 MB)

Flag	Default	Description
--version	manifest default	Model version, e.g. `1.0`, `2.0`. See `--list` for what's available.
--params	version default	Parameter-count label within the chosen version, e.g. `open-base`, `4m`, `1b`.
--variant	preferred	File variant: `f16` (half-precision) or `f32` (full precision). Defaults to `f16` when available, else `f32`. Toto 2.0 currently ships f32 only.
--list	false	Print available versions / parameter counts / variants for the model and exit without pulling.

routeframe serve

routeframe serve [flags]

Start a REST API server. Models stay warm between requests for low-latency repeated inference.

$ routeframe serve
Routeframe server listening on 127.0.0.1:11435

# Call it from anywhere on the same machine
$ curl -s localhost:11435/api/forecast \
    -d '{"model":"toto","input":[[10,12,11,14]],"prediction_length":4}' | jq .
{
  "model": "toto",
  "mean": [14.82, 15.31, 15.78, 16.20],
  "inference_time_ms": 4
}

Flag	Default	Description
--port	11435	Port to listen on.
--host	127.0.0.1	Host address to bind.

routeframe finetune

routeframe finetune [flags]

Adapt a foundation model to your own time series data. Requires the managed Python environment (routeframe env setup).

# Basic fine-tuning from a CSV
$ routeframe finetune --data sales.csv --model toto
Setting up fine-tuning environment...
Loading data from sales.csv (1,247 rows)
Training: epoch 1/10 ████████░░░░░ 63% | loss: 0.241
Training: epoch 2/10 ████████████░ 98% | loss: 0.198
...
Fine-tuned model saved: ~/.routeframe/models/.finetune/toto-ft/

# With exogenous variables
$ routeframe finetune \
    --data metrics.csv \
    --model toto \
    --targets "cpu_usage" \
    --exogenous "is_deploy,day_of_week" \
    --epochs 20 \
    --output my-model

# Use your fine-tuned model
$ routeframe run my-model --input "45,48,52,49,55" --horizon 8

# Fine-tune TimesFM 2.5
$ routeframe finetune \
    --model timesfm \
    --data sales.csv \
    --targets "revenue" \
    --epochs 10 \
    --output my-timesfm
Fine-tuning TimesFM 2.5 on sales.csv
  Target:  revenue
  Epochs:  10
  Output:  my-timesfm

Loading google/timesfm-2.5-200m-transformers ...
  Device: mps
  Dataset: 3,840 windows (context=512, horizon=32)
  epoch 1/10  step 120/120  loss=0.8421  lr=3.00e-05
Epoch 1/10 complete — avg loss: 0.8421
...
Fine-tuned model ready: my-timesfm

Flag	Default	Description
--data	required	Path to CSV training data.
--model	toto	Base model to fine-tune: `toto` or `timesfm`.
--targets	auto	Target column names. Comma-separated for toto; single column name for timesfm.
--exogenous	—	Known-future covariate columns (toto only).
--output	—	Name for the fine-tuned model.
--steps	1400	Training steps (toto).
--epochs	10	Training epochs (timesfm).
--lr	4e-5	Learning rate.
--batch-size	16	Training batch size.

routeframe list

List all downloaded models and their sizes.

$ routeframe list
NAME                 ARCH         VERSION                   SIZE
----                 ----         -------                   ----
toto                 toto         2.0/1b/f32                3.9 GB
toto                 toto         2.0/4m/f32                16 MB
timesfm              timesfm      -                         441.4 MB
chronos2             chronos2     -                         228.0 MB

Each variant on disk is its own row. The VERSION column shows what routeframe pull resolved when the file was last downloaded, parsed from a small JSON sidecar next to the GGUF. A dash means the file was pulled by a pre-v0.7.0 client that didn't write a sidecar (still works fine for inference).

routeframe rm

routeframe rm <model> [flags]

Remove downloaded variants from disk to free up space.

# Single variant on disk -- just remove it
$ routeframe rm timesfm
Removed timesfm.gguf (441.4 MB freed)

# Multiple variants -- pick one
$ routeframe rm toto --params 1b
Removed toto-2.0-1b-f32.gguf (3.9 GB freed)

# Or remove everything for that model
$ routeframe rm toto --all
Removed 3 variants of toto (5.2 GB freed):
  toto-2.0-4m-f32.gguf
  toto-2.0-22m-f32.gguf
  toto-2.0-1b-f32.gguf

With several variants on disk and no scoping flags, the command lists what's there and exits without deleting anything -- destructive defaults are kept conservative.

Flag	Default	Description
--params	—	Parameter-count label to remove (e.g. `1b`, `4m`, `open-base`).
--version	—	Version to remove (e.g. `1.0`, `2.0`).
--variant	—	File variant to remove (e.g. `f16`, `f32`).
--all	false	Remove every variant of the model.

routeframe monitor

routeframe monitor [flags]

Live forecast monitoring: pipe real-time metric values into routeframe and watch a rolling chart with the forecast overlay update in your terminal.

# Pipe CPU usage into live chart — one value per line
$ top -bn1 | awk '/Cpu/ {print $2}' | routeframe monitor --model toto --horizon 8

# Replay from a log file
$ tail -f metrics.log | routeframe monitor --model toto --horizon 12

Flag	Default	Description
--model	toto	Model to use for forecasting.
--horizon	8	Steps ahead to forecast on each update.
--window	50	Number of recent data points to display in the chart.

routeframe upgrade

Re-runs the install script and replaces the binary at its current location. Models are not affected.

$ routeframe upgrade
Upgrading routeframe...
  Platform: darwin/arm64
  Existing: /usr/local/bin/routeframe (will be replaced)
  Install:  /usr/local/bin/routeframe

Downloading...
Routeframe installed successfully!

routeframe env

routeframe env <subcommand>

Manage the managed Python runtime used by forecast and finetune. Uses uv internally and installs to ~/.routeframe/python/.

# Show status
$ routeframe env info
Python environment: installed
Location:   ~/.routeframe/python
Python:     ~/.routeframe/python/bin/python
GPU:        mps
Packages:   72 installed

# Install (first time)
$ routeframe env setup
Installing Python 3.11...
Installing PyTorch and dependencies...
Python environment ready.

# Reset (reinstall from scratch)
$ routeframe env reset

# Remove entirely
$ routeframe env remove

Subcommand	Description
info	Show Python path, version, installed packages, and GPU availability.
setup	Install the Python environment. No-op if already installed.
reset	Remove and reinstall the environment from scratch.
remove	Delete the environment entirely.