Terminal App

An interactive guide to the Routeframe TUI — navigate models, run forecasts, and manage your environment without memorising commands.

Launching the app

Run routeframe with no arguments to open the interactive terminal UI:

$ routeframe

The app takes over the full terminal window (alt-screen mode). Your previous shell output is preserved and restored when you quit.

First time? Pull a model before running your first forecast — press ↓ to reach Pull a model and hit Enter.

Welcome screen overview

The welcome screen shows a system information panel and a navigation menu:

████████████████████████████████████████████████████████████
 ROUTEFRAME
                Run time series foundation models locally

System Information:
  * Device: Apple Silicon (Metal)
  * Models: toto, timesfm
  * Version: v0.7.3
  * Status: Ready

? What would you like to do?
> Auto-select best model
    Probe all pulled models on your data and recommend the winner
  Run a forecast
  Start API server
  Pull a model
  Fine-tune a model
  Manage environment

  ↑↓ navigate · enter select · q quit

The system panel tells you:

Device — hardware backend (Metal on Apple Silicon, CUDA on NVIDIA, CPU otherwise)
Models — which foundation models are already downloaded
Version — the installed binary version
Status — Ready once the binary and at least one model are in place

Key	Action	Where
↑ / k	Move selection up	Any menu
↓ / j	Move selection down	Any menu
Enter	Select / confirm	Any menu
Escape	Go back to welcome screen	Any sub-screen
Tab	Switch between input fields	Forecast input screen
q	Quit the app	Welcome screen only
Ctrl+C	Force quit	Anywhere

Note: q types the letter q on input screens — it only quits from the welcome screen. Use Escape to back out of any sub-screen first.

Auto-selecting the best model

Select Auto-select best model at the top of the welcome menu when you have a CSV (or Parquet, DuckDB, SQLite, HTTP URL) and you're not sure which foundation model fits the data. The TUI prompts for a single file path and shells out to routeframe auto; the ranked output and recommendation appear directly below.

Auto-select best model

  Probe every locally-pulled foundation model on a held-out portion of
  your data, then recommend the best one with bootstrap-CI ranking and
  daily/weekly naive baselines.

  Data file:
  > /path/to/data.csv_

  Supported: CSV, Parquet, Arrow/Feather, DuckDB, SQLite, HTTP/S URLs
  Tip: drag a file into the terminal to paste its path

  Will probe: timesfm, toto, chronos2

  enter to run · escape to go back

What happens after you press Enter:

Stage 1: every pulled model is run on a small held-out window set; the bottom half are dropped.
Stage 2: the survivors and seasonal naive baselines (daily lag, weekly lag) get a full evaluation with 1,000-sample bootstrap 95% CIs.
A ranked table is printed, then a recommendation with reasoning -- including whether fine-tuning is likely to help based on dataset size.

When to use this first. If you've never benchmarked your dataset, run Auto-select before Run a forecast or Fine-tune. It will tell you whether the best zero-shot model already beats every reasonable baseline (in which case you can skip fine-tuning entirely) or whether your data is unusual enough to need adaptation. The whole probe finishes in 5-10 seconds for 4 candidate models.

Running a forecast

Select Run a forecast and press Enter. You move through three screens in sequence.

Model selection — choose from downloaded models with ↑ / ↓, then press Enter.

Select a model

> toto
  timesfm
  chronos2

  enter select · escape back

Only models you've already pulled are shown. If the list is empty, press Escape and use Pull a model first.

Data input — enter your time series as comma-separated numbers and set the horizon. Use Tab to switch between fields.

Forecast with toto

Input data (comma-separated):
  45, 48, 52, 49, 55, 58, 62, 59, 64, 67

Prediction horizon:
  8

  tab switch fields · enter run · escape back

Leave either field empty to use the placeholder value. The input field is active by default (highlighted label).

Results — the model runs inference and shows an ASCII chart plus point predictions.

Forecast Results

 68 ┤                                    ╭─
 64 ┤                               ╭───╯
 60 ┤                       ╭───────╯
 56 ┤          ╭─╮     ╭────╯
 52 ┤     ╭────╯ ╰─────╯
 48 ┼─────╯
              historical (10)    forecast (8)

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

  enter to go back

Press Enter or Escape to return to the welcome screen.

Pulling a model

Select Pull a model to browse the registry. The list is fetched from the registry's index.json at launch (with a 3-second timeout and a baked-in fallback), so new models show up here without re-installing routeframe.

Pull a model
  Select a model, then choose a version / size

> toto  (3 variants downloaded)
    Datadog · 4M – 2.5B params · 16 MB – 9.1 GB
  timesfm  (1 variant downloaded)
    Google · 200M params · 441 MB
  chronos2
    Amazon · 120M params · 228 MB

  enter select · escape back

Each row shows the parameter and size range across all variants. The green suffix counts how many variants you have on disk for that model. Specific identities (which versions / params / variants) live in the drill-down screen below, where every locally-pulled row is individually marked.

Choose a variant

Pressing Enter on a model opens a drill-down listing every (version / params / variant) tuple in the manifest. The cursor lands on the manifest's default (latest version, smallest params, preferred variant). Every variant already on disk gets a (downloaded) marker -- multiple variants of the same model coexist, so the drill-down can have several rows marked at once.

Pull toto -- choose a variant
  Pick a (version / params / variant) combination

   VER    PARAMS        VAR   SIZE
   1.0    Open-Base     f16   289 MB
   1.0    Open-Base     f32   577 MB
   2.0    1B            f32   3.9 GB    (downloaded)
   2.0    2.5B          f32   9.1 GB
   2.0    22M           f32   84 MB     (downloaded)
   2.0    313M          f32   1.2 GB
> 2.0    4M            f32   16 MB     (default, downloaded)

  enter download · escape back

Pressing Enter hands off to routeframe pull <model> --version <V> --params <P> --variant <K> and shows a live progress bar. The app resumes when the download finishes.

Storage: Each variant lives in its own file under ~/.routeframe/models/ (e.g. toto-2.0-1b-f32.gguf), with a sidecar .gguf.json alongside. Pulling a new variant does not overwrite the others -- you can keep several sizes side by side and switch between them. Files survive upgrades; you never need to re-pull after updating routeframe.

Built-in models

toto — Datadog's Toto family. Toto 2.0 ships five sizes (4M, 22M, 313M, 1B, 2.5B parameters, all f32) plus the legacy Toto 1.0 / Open-Base (f16 and f32). Multivariate; the 1.0 line is fine-tunable.
timesfm — Google's TimesFM 2.5, 441 MB. Single-shot 128-step horizon with 9 quantile levels.
chronos2 — Amazon Chronos 2, 228 MB. Encoder-only, 21 quantile levels, up to 8K context.

Starting the API server

Select Start API server to see the endpoint overview, then press Enter to launch.

Start API server

  The REST API server will start on:
    http://localhost:11435

  Endpoints:
    POST /api/forecast     — run a forecast
    POST /api/pull         — download a model
    GET  /api/models       — list models
    GET  /health           — health check

  Press enter to start (Ctrl+C to stop)
  escape to go back

The TUI exits alt-screen and starts routeframe serve directly. The server runs until you press Ctrl+C, after which you're returned to the shell.

$ curl -s localhost:11435/api/forecast \
    -d '{"model":"toto","input":[45,48,52,49,55],"horizon":4}' | jq .
{
  "mean": [58.2, 61.1, 59.8, 63.4]
}

Fine-tuning

Select Fine-tune a model to see step-by-step instructions for training on your own data.

Fine-tune a model

  Adapt a foundation model to your own time series data.

  1. Prepare a CSV with a timestamp column and value columns.
  2. Run:
       routeframe finetune --data your_data.csv --model toto

  3. The fine-tuned model is saved to ~/.routeframe/models/.finetune/

  Options:
    --model      toto (default)
    --epochs     training epochs (default 10)
    --exogenous  known future variable columns

  enter or escape to go back

Fine-tuning runs outside the TUI. Copy the shown command into a separate terminal where you can watch live training output.

Requirements: Fine-tuning needs a Python environment. Run routeframe env setup once to install the managed runtime.

Managing the environment

Select Manage environment to inspect paths, installed models, and Python status.

Environment

  Binary:     /usr/local/bin/routeframe
  Models dir: /Users/you/.routeframe/models
  OS:         darwin/arm64
  Downloaded: toto, timesfm
  Python:     /Users/you/.routeframe/python/bin/python3

  enter or escape to go back

If Python shows not installed, run routeframe env setup from a shell to install the managed Python runtime (required for fine-tuning and the forecast command).

Version & updates

The welcome screen always shows the installed version. When a newer release is available, a bright yellow banner appears:

  ↑↓ navigate · enter select · q quit

  Update available: v0.7.2 → v0.7.3   run: routeframe upgrade

Version checks are cached for 24 hours so they never block startup. To upgrade, exit the TUI and run:

$ routeframe upgrade
Upgrading routeframe...
Routeframe installed successfully!

The binary is replaced in-place at its current path. Models on disk are not affected.

Terminal App

Launching the app

Welcome screen overview

Navigation & key bindings

Auto-selecting the best model

Running a forecast

Pulling a model

Choose a variant

Built-in models

Starting the API server

Fine-tuning

Managing the environment

Version & updates