Runner CLI¶

The tuneline command executes pipeline runs: one run from the app (run), queued runs on your own computer (worker), a pipeline YAML file offline (run-local), and a check of the machine (doctor).

The same runner (version 0.1.0) runs inside every cloud job, in notebooks and on your computer. You rarely type these commands yourself: the app shows the exact command with the token filled in. This page is the exact reference for when you do.

Install¶

With the installer (recommended). It creates a virtual environment in ~/.tuneline/venv (%USERPROFILE%\.tuneline\venv on Windows), installs PyTorch (the CUDA build when an NVIDIA GPU is found, the Apple silicon build on macOS, the CPU build otherwise), installs the runner that matches the app, and starts it. Settings → Your computers → Add a computer shows these commands with your worker token; see Your computer.

# Linux / macOS: start a worker for "My computer" runs
curl -fsSL https://tuneline-studio.vercel.app/runner/install.sh | bash -s -- --worker-token tlw_...
# run one run now
curl -fsSL https://tuneline-studio.vercel.app/runner/install.sh | bash -s -- --run-token tlr_...
# install or update only
curl -fsSL https://tuneline-studio.vercel.app/runner/install.sh | bash

# Windows PowerShell: set up a worker (runs hidden and starts with Windows)
$env:TUNELINE_WORKER_TOKEN='tlw_...'; irm https://tuneline-studio.vercel.app/runner/install.ps1 | iex
# run one run now
$env:TUNELINE_RUN_TOKEN='tlr_...'; irm https://tuneline-studio.vercel.app/runner/install.ps1 | iex
# install or update only
irm https://tuneline-studio.vercel.app/runner/install.ps1 | iex

install.sh options: --worker-token TOKEN, --run-token TOKEN, --cpu (CPU build of PyTorch), --home DIR (instead of ~/.tuneline), --no-start (install only). Both installers need Python 3.10 to 3.13; running them again updates the runner in place (it is force-reinstalled so it always matches the app).

With pip. Install PyTorch for your hardware first (pytorch.org), then the runner package from the app:

python -m pip install "tuneline[train,gguf] @ https://tuneline-studio.vercel.app/runner/tuneline-0.1.0-py3-none-any.whl"
tuneline --version

Optional extras (from pyproject.toml):

Extra	Installs	Needed for
`train`	`transformers>=5.0,<6`, `datasets>=4.7`, `peft>=0.18`, `trl>=1.0,<2`, `accelerate>=1.4`, `bitsandbytes>=0.46` (not on macOS), `sentencepiece`, `protobuf`, `safetensors`, `pillow`	Training, evaluation, merging: any real run
`gguf`	`gguf>=0.10`	Export GGUF
`eval`	`lm-eval>=0.4.8`	Benchmarks (lm-eval)
`unsloth`	`unsloth`	Use Unsloth (falls back to standard TRL while Unsloth needs an older TRL)
`vllm`	`vllm`	The vLLM generation backend of Evaluate on test set (NVIDIA GPUs)
`deploy`	`modal>=1.0`	Deploy endpoint with the Modal provider
`api`	`fastapi>=0.115`, `modal>=1.5,<2`, `kagglesdk>=0.1.30`	The control plane (developers)
`dev`	`pytest>=8`, `pytest-asyncio`	Tests (developers)

Without extras the runner has only its base dependencies (httpx, pyyaml, huggingface_hub>=1.5,<2.0, pandas, pyarrow, psutil). Jobs install tuneline[train,gguf]; heavier packages (lm-eval, vLLM, Unsloth, llama.cpp) are installed on first use by the block that needs them, unless TUNELINE_NO_AUTO_INSTALL is set.

tuneline¶

usage: tuneline [-h] [--version] {run,worker,run-local,doctor} ...

Tuneline Studio runner: execute pipeline runs.

positional arguments:
  {run,worker,run-local,doctor}
    run                 Execute one run created in Tuneline.
    worker              Run queued 'My computer' runs on this machine.
    run-local           Run a pipeline YAML file offline, without Tuneline.
    doctor              Check this machine: Python, GPU, packages, tools,
                        connectivity.

options:
  -h, --help            show this help message and exit
  --version             show program's version number and exit

tuneline --version prints tuneline 0.1.0. You can also call the CLI as python -m tuneline.runner.cli.

tuneline run¶

Executes one run created in the app, reporting steps, logs, metrics and artifacts live to the run page.

usage: tuneline run [-h] [--token TOKEN] [--supabase-url SUPABASE_URL]
                    [--supabase-key SUPABASE_KEY] [--workdir WORKDIR]

options:
  -h, --help            show this help message and exit
  --token TOKEN         Run token (tlr_...). Default: TUNELINE_RUN_TOKEN.
  --supabase-url SUPABASE_URL
                        Override TUNELINE_SUPABASE_URL.
  --supabase-key SUPABASE_KEY
                        Override TUNELINE_SUPABASE_KEY.
  --workdir WORKDIR     Work folder (default: TUNELINE_WORKDIR or
                        ~/.cache/tuneline).

What it does:

Loads the run with the token: the compiled spec, the API keys the pipeline needs (exported as HF_TOKEN, WANDB_API_KEY and so on, never printed) and your profile.
Executes the steps in order. Steps whose inputs and settings were already computed are reused from the cache when the run allows it; failed upstream steps make later steps skipped.
Stops itself at the run's time limit (max_hours) or cost limit (max_cost_usd at the estimated hourly price), whichever comes first, and reports cancelled with the reason.
Honours cancellation from the app at the next safe point (training checks every step).

The run token can also come from TUNELINE_RUN_TOKEN; prefer that on shared machines so the token does not show in process listings. Get a command with a token from the run page (Notebook or My computer targets) or GET /api/runs/{id}/command.

Ctrl+C (or SIGTERM) stops at the next safe point and reports cancelled; a second Ctrl+C stops immediately. Events that cannot be delivered after retries are written to <workdir>/runs/<run_id>/undelivered-events.jsonl.

Exit code	Meaning
`0`	The run succeeded (or had already succeeded).
`1`	The run failed or was cancelled, or the token was rejected.
`2`	No token given.
`130`	Interrupted.

tuneline worker¶

Runs queued My computer runs on this machine. It sends a heartbeat with system and GPU information every 30 seconds, claims runs assigned to this computer, and executes each one in a child tuneline run process (the run token is passed through the environment, not the command line).

usage: tuneline worker [-h] [--token TOKEN] [--poll-interval POLL_INTERVAL]
                       [--once] [--supabase-url SUPABASE_URL]
                       [--supabase-key SUPABASE_KEY] [--workdir WORKDIR]

options:
  -h, --help            show this help message and exit
  --token TOKEN         Worker token (tlw_...). Default:
                        TUNELINE_WORKER_TOKEN.
  --poll-interval POLL_INTERVAL
                        Seconds between checks for new runs.
  --once                Exit after one run.
  --supabase-url SUPABASE_URL
                        Override TUNELINE_SUPABASE_URL.
  --supabase-key SUPABASE_KEY
                        Override TUNELINE_SUPABASE_KEY.
  --workdir WORKDIR     Work folder (default: TUNELINE_WORKDIR or
                        ~/.cache/tuneline).

Option	Default
`--token`	`TUNELINE_WORKER_TOKEN`
`--poll-interval`	`10` seconds
`--once`	off: keep waiting for runs
`--workdir`	`TUNELINE_WORKDIR`, else `~/.cache/tuneline`

Create the worker token under Settings → Your computers → Add a computer; it is shown once and works until you remove that computer. When the worker connects it prints Worker '<name>' is online (…). Waiting for runs... Press Ctrl+C to stop. and the computer turns online in Settings. Ctrl+C asks the current run to stop cleanly; a second Ctrl+C forces it. The worker exits with 2 when no token is given and stops when the token is rejected.

tuneline worker --token tlw_...
TUNELINE_WORKER_TOKEN=tlw_... tuneline worker --once

On Windows the installer runs the worker hidden through %USERPROFILE%\.tuneline\start-worker.ps1 with a Tuneline worker shortcut in the Startup folder; its log is %USERPROFILE%\.tuneline\worker.log and %USERPROFILE%\.tuneline\stop-worker.ps1 stops it.

tuneline run-local¶

Runs a pipeline YAML file (exported from the canvas's YAML tab) on this machine without the app: no sign-in, no live run page, and no cache across runs. Useful for tests, scripts and CI. See Pipeline YAML for the file format.

usage: tuneline run-local [-h] [--set NODE.PARAM=VALUE] [--dataset ID=FILE]
                          [--app-url APP_URL] [--events EVENTS]
                          [--workdir WORKDIR] [--quiet]
                          pipeline

positional arguments:
  pipeline              Pipeline YAML (exported from the canvas).

options:
  -h, --help            show this help message and exit
  --set NODE.PARAM=VALUE
                        Override a setting, e.g. --set
                        base.repo_id=Qwen/Qwen3-0.6B (repeatable).
  --dataset ID=FILE     Use a local file for an uploaded dataset version
                        (repeatable).
  --app-url APP_URL     Value of {app_url} (default: TUNELINE_APP_URL).
  --events EVENTS       Also write every event to this JSONL file.
  --workdir WORKDIR     Work folder (default: TUNELINE_WORKDIR or
                        ~/.cache/tuneline).
  --quiet               Print log lines only.

Option	Details
`--set NODE.PARAM=VALUE`	`NODE` is a step id, `PARAM` a setting key from the Block reference. Values are strings; for `json` settings, and for list settings written as `[...]`, the value is parsed as JSON. Unknown steps or settings stop with a list of the valid ones.
`--dataset ID=FILE`	Replaces an uploaded dataset (a Load dataset step with `dataset_version_id: ID`) by a local file.
`--app-url`	Needed when a setting uses `{app_url}`, for example the template samples: `--app-url https://tuneline-studio.vercel.app`.
`--events`	Writes every runner event (logs, metrics, steps, artifacts) as JSON lines.
`--quiet`	Prints log lines only.

API keys come from the environment: HF_TOKEN (or HUGGING_FACE_HUB_TOKEN), WANDB_API_KEY, OPENAI_COMPAT_API_KEY, OPENAI_COMPAT_BASE_URL, RUNPOD_API_KEY, MODAL_TOKEN_ID, MODAL_TOKEN_SECRET, KAGGLE_API_TOKEN, KAGGLE_USERNAME, KAGGLE_KEY, or TUNELINE_<KEY NAME IN CAPITALS> such as TUNELINE_HF_TOKEN.

At the end it lists each output as step.port: uri. Exit code 0 when the run succeeded, 1 when it failed or was cancelled, 2 when the file is missing or the pipeline is not valid (the errors are printed).

tuneline run-local cpu-smoke-test.yaml --app-url https://tuneline-studio.vercel.app \
  --set base.repo_id=HuggingFaceTB/SmolLM2-135M-Instruct --events events.jsonl

tuneline doctor¶

Checks this machine and prints a report: Python, CPU, RAM and free disk, PyTorch and CUDA, GPUs, the versions of the training packages (with warnings for versions older than the runner was tested with), tools (git, cmake, c++, ollama, nvidia-smi), the work folder and llama.cpp, whether HF_TOKEN is set, and whether Tuneline's database, the Hugging Face Hub, PyPI and GitHub can be reached.

usage: tuneline doctor [-h] [--offline] [--self-test] [--workdir WORKDIR]

options:
  -h, --help         show this help message and exit
  --offline          Skip the connectivity checks.
  --self-test        Also train a tiny model for two steps.
  --workdir WORKDIR

--self-test builds a tiny random model and trains it for two steps on built-in examples, offline, then evaluates it: a quick check that the training stack works. The command ends with All good. (exit code 0) or Some problems were found (see above). (exit code 1), for example when Python is older than 3.10, PyTorch is missing or one of transformers, trl, peft, datasets is not installed.

Environment variables¶

Runner

Variable	Used by	Meaning
`TUNELINE_RUN_TOKEN`	`run`	Run token (`tlr_…`) when `--token` is not given.
`TUNELINE_WORKER_TOKEN`	`worker`	Worker token (`tlw_…`) when `--token` is not given.
`TUNELINE_SUPABASE_URL`	`run`, `worker`, `doctor`	Database address. Default: the hosted project, baked into the package.
`TUNELINE_SUPABASE_KEY`	`run`, `worker`, `doctor`	Public database key. Default: baked into the package.
`TUNELINE_WORKDIR`	all	Work folder. Default `~/.cache/tuneline`.
`TUNELINE_APP_URL`	`run`, `run-local`	Value of `{app_url}` when the run's settings do not give one.
`TUNELINE_TOOLS_DIR`	all	Where tools such as llama.cpp are downloaded. Default `<workdir>/tools`.
`TUNELINE_LLAMA_CPP_DIR`	Export GGUF, `doctor`	An existing llama.cpp checkout to use. Default `<tools>/llama.cpp`.
`TUNELINE_NO_AUTO_INSTALL`	blocks	Set to any value to stop blocks from installing missing packages; they fail (or warn) with the `pip install` command instead.
`TUNELINE_DEBUG`	all	Set to any value to print debug log lines and full tracebacks.
`TUNELINE_HF_ROUTER_URL`	LLM judge, synthetic data	Override the Hugging Face Inference Providers address.
`TUNELINE_<KEY>`	`run-local`	An API key, e.g. `TUNELINE_HF_TOKEN` (see run-local).

Cloud jobs and notebooks also set TUNELINE_VERSION, TUNELINE_WHEEL_URL and TUNELINE_RUN_ID for the launch script.

Installers

Variable	Meaning
`TUNELINE_APP_URL`	The app's address (already filled in when you download the installer from the app).
`TUNELINE_WHEEL_URL`	Where to download the runner package.
`TUNELINE_HOME`	Install folder. Default `~/.tuneline` (`%USERPROFILE%\.tuneline` on Windows).
`TUNELINE_TORCH`	`auto` (default), `cpu` or `skip` (keep the PyTorch you have).
`TUNELINE_PYTHON`	Python to use (`install.sh` only).
`TUNELINE_WORKER_TOKEN`, `TUNELINE_RUN_TOKEN`	Start a worker or one run after installing.
`TUNELINE_NO_START=1`	Install only (`install.ps1`; `install.sh` uses `--no-start`).
`TUNELINE_NO_AUTOSTART=1`	Windows: don't add the worker to the Startup folder.
`TUNELINE_FOREGROUND=1`	Windows: run the worker in the current window instead of hidden.

Note

On Windows, LoRA and full fine-tuning work natively; QLoRA (bitsandbytes) and Unsloth are most reliable under WSL2 (Ubuntu) with the Linux installer.