Transformer Lab CLI
Transformer Lab can be accessed via CLI using the lab executable.
Install​
The CLI is distributed as a Python package and can be installed using uv:
uv tool install transformerlab-cli
This adds a lab command to your terminal. To upgrade to the latest version:
uv tool upgrade transformerlab-cli
Requires Python 3.10 or higher. If you don't have uv installed, you can install it with:
curl -LsSf https://astral.sh/uv/install.sh | sh
See the uv installation guide for more options.
Global Options​
lab [OPTIONS] COMMAND [ARGS]...
| Option | Description | Default |
|---|---|---|
--format | Output format: pretty or json | pretty |
--help | Show help message and exit |
Commands​
version​
Display the CLI version.
lab version
status​
Check the status of the server and configuration.
lab status
login​
Log in to Transformer Lab. Prompts for server URL and API key if not provided.
# Interactive login (prompts for server and API key)
lab login
# Login with options
lab login --server https://my-server:8338 --api-key YOUR_API_KEY
| Option | Description |
|---|---|
--api-key | Your API key |
--server | Server URL |
logout​
Log out from Transformer Lab by deleting the stored API key.
lab logout
whoami​
Show the current logged-in user, team information, and server.
lab whoami
# JSON output
lab --format json whoami
install-agent-skill​
Install the Transformer Lab agent skill so AI coding agents (Claude Code, etc.) know how to drive the lab CLI for you. Wraps npx skills add transformerlab/transformerlab-app --skill transformerlab-cli, so Node.js (which provides npx) must be installed.
lab install-agent-skill
config​
View or set configuration values.
# View all configuration values
lab config
# Get a single configuration value
lab config get <key>
# Set a configuration value
lab config set <key> <value>
# Examples
lab config set server http://localhost:8000
lab config set current_experiment my_experiment
| Argument | Description |
|---|---|
key | Config key to set |
value | Config value to set |
task​
Task management commands. Requires current_experiment to be set in config.
Every task subcommand accepts --experiment / -e <id_or_name> to override the configured default for a single invocation.
task list​
List all remote tasks in the current experiment.
lab task list
task init​
Initialize a task.yaml and main.py in the current directory using the bundled template.
# Write the default files into the current directory
lab task init
# Prompt for task settings instead of using defaults
lab task init --interactive
# Overwrite an existing task.yaml without asking
lab task init --force
| Option | Description |
|---|---|
--interactive | Prompt for task settings instead of using defaults. |
--force | Overwrite an existing task.yaml without prompting. |
task add​
Add a new task from a local directory or a Git repository.
# Add from a local directory containing task.yaml
lab task add ./my-task-directory
# Preview without creating (dry run)
lab task add ./my-task-directory --dry-run
# Add from a Git repository
lab task add --from-git https://github.com/user/repo
| Argument | Description |
|---|---|
task_directory | Path to the task directory containing task.yaml |
| Option | Description |
|---|---|
--from-git | Git URL to fetch the task from |
--dry-run | Preview the task without creating it |
task upload​
Upload additional files into an existing task (e.g. add a new dataset or helper script alongside task.yaml).
lab task upload <task_id> ./extra-file.py
lab task upload <task_id> ./assets/ # directory
lab task upload <task_id> ./extra-file.py --no-interactive
| Argument | Description |
|---|---|
task_id | Task ID to upload files to. |
path | Path to a file or directory to upload. |
| Option | Description |
|---|---|
--no-interactive | Skip confirmation prompts. |
task validate​
Validate a task.yaml file against the server-side schema.
# Validate ./task.yaml
lab task validate
# Validate a specific YAML file
lab task validate ./path/to/task.yaml
| Argument | Description |
|---|---|
task_yaml_path | Path to task.yaml (defaults to ./task.yaml) |
| Option | Description |
|---|---|
--timeout | Request timeout in seconds for validation |
task info​
Get detailed information for a specific task.
lab task info <task_id>
task queue​
Queue a task on a compute provider. Interactively prompts for provider selection and parameter values.
# Interactive mode (prompts for provider and parameters)
lab task queue <task_id>
# Non-interactive mode (uses defaults)
lab task queue <task_id> --no-interactive
# Override task parameters for this run only (repeatable). Values are parsed as
# YAML scalars: epochs=3 -> int, lr=0.001 -> float, enabled=true -> bool.
lab task queue <task_id> --param epochs=3 --param lr=0.001
# Attach a run description (like a commit description). '-' reads from stdin.
lab task queue <task_id> --description "first run from CLI"
echo "long description" | lab task queue <task_id> -m -
# Enable system or torch profiling for this run.
lab task queue <task_id> --enable-profiling
lab task queue <task_id> --enable-profiling --enable-profiling-torch
| Option | Description |
|---|---|
--no-interactive | Skip interactive prompts and use defaults. |
--param, -p KEY=VALUE | Override a task parameter for this queue (repeatable). Unknown keys fail. Values are YAML scalars. |
--description, -m TEXT | Markdown note for this run. Pass - to read from stdin. |
--enable-profiling | Enable system profiling (CPU/GPU/memory sampling). |
--enable-profiling-torch | Enable torch profiler trace export (requires --enable-profiling). |
task interactive​
Launch an interactive task (Jupyter, vLLM, Ollama, etc.) and wait for the service to become reachable.
lab task interactive
lab task interactive --timeout 600 # wait up to 10 minutes for readiness
| Option | Description |
|---|---|
--timeout, -t | Timeout in seconds waiting for service readiness (default: 300). |
task gallery​
Browse the task gallery. Optionally import a task into the current experiment.
# List all gallery tasks
lab task gallery
# List interactive templates only
lab task gallery --type interactive
# Import directly (non-interactive)
lab task gallery --import <gallery_id>
| Option | Description |
|---|---|
--type | Gallery type: all (default) or interactive |
--import | Gallery ID to import as a task (skips interactive prompt) |
task edit​
Edit an existing task. Interactive editor by default; use --from-file to replace only task.yaml, or --from-dir to replace task.yaml plus sibling files (e.g. main.py).
# Open task.yaml in $EDITOR (interactive)
lab task edit <task_id>
# Replace task.yaml from a local file
lab task edit <task_id> --from-file ./task.yaml
# Replace task.yaml and any sibling files (e.g. main.py) from a directory
lab task edit <task_id> --from-dir ./my-task
# Preview a --from-dir update without submitting
lab task edit <task_id> --from-dir ./my-task --dry-run
| Option | Description |
|---|---|
--from-file | Path to task.yaml to apply directly (mutually exclusive with --from-dir). |
--from-dir | Path to a directory containing task.yaml (and any attachments) to replace task contents. |
--dry-run | Preview the task update without submitting it (only applies with --from-dir). |
--no-interactive | Skip confirmation prompts. |
--timeout | Request timeout in seconds for fetch/validate/save. |
task delete​
Delete a task by ID.
lab task delete <task_id>
job​
Job management commands. Most subcommands require current_experiment to be set in config.
Every job subcommand accepts --experiment / -e <id_or_name> to override the configured default for a single invocation.
job list​
List all jobs for the current experiment.
# All jobs in the current experiment
lab job list
# Only currently-active jobs (WAITING, LAUNCHING, RUNNING, INTERACTIVE)
lab job list --running
# Sort by a recorded score metric. Defaults to descending.
lab job list --score-metric eval/loss --score-order asc
| Option | Description |
|---|---|
--running | Show only active jobs (WAITING, LAUNCHING, RUNNING, INTERACTIVE). |
--score-metric, --sort-by | Sort jobs by this score metric key (e.g. eval/loss). |
--score-order | Score ordering direction: desc (default) or asc. |
job info​
Get detailed information for a specific job.
lab job info <job_id>
job artifacts​
List artifacts for a specific job. Includes filename, path, and size (when available).
lab job artifacts <job_id>
job download​
Download artifacts for a job.
# Download all as zip (existing behavior)
lab job download <job_id>
# Download a single file
lab job download <job_id> --file model.bin
# Download files matching a glob pattern
lab job download <job_id> --file "*.json"
# Download multiple specific files
lab job download <job_id> --file weights.bin --file config.json
# Download to a specific directory
lab job download <job_id> --file "*.ckpt" --output ./checkpoints
| Option | Description |
|---|---|
--file | Filename or glob pattern (repeatable). Omit to download all as zip. |
-o, --output | Output directory (default: current directory) |
job metrics​
Show training metrics for a job. By default prints the last N rows; --follow polls and streams new rows.
# Last 20 rows (default tail)
lab job metrics <job_id>
# Last 50 rows
lab job metrics <job_id> --tail 50
# Stream new rows until interrupted
lab job metrics <job_id> --follow
# Restrict to specific metric keys
lab job metrics <job_id> --keys train/loss,eval/loss
# Raw JSONL output (for piping to jq etc.)
lab job metrics <job_id> --json
| Option | Description |
|---|---|
--follow, -f | Poll for new metric rows until interrupted. |
--tail, -n N | Show last N rows (default: 20; ignored with --follow). |
--keys k1,k2,... | Comma-separated metric keys to display. |
--json | Emit raw JSONL rows to stdout. |
job machine-logs​
Fetch provider/machine logs for a job (the host process's stdout/stderr).
lab job machine-logs <job_id>
lab job machine-logs <job_id> --follow
| Option | Description |
|---|---|
--follow, -f | Stream new lines continuously. |
job task-logs​
Fetch task output (Lab SDK) for a job. This is usually the most useful log for understanding what the user code did.
lab job task-logs <job_id>
lab job task-logs <job_id> --follow
| Option | Description |
|---|---|
--follow, -f | Stream new lines continuously. |
job request-logs​
Fetch provider request/launch logs (e.g. SkyPilot launch logs) for a job. Useful when a job fails before user code runs.
lab job request-logs <job_id>
job stop​
Stop a running job and tear down its provider cluster.
lab job stop <job_id>
job discard​
Toggle the discard flag on a job's score record. Discarded jobs are still kept but hidden from default scoring views.
# Mark a job as discarded
lab job discard <job_id>
# Undo the discard
lab job discard <job_id> --undo
| Option | Description |
|---|---|
--undo | Unset discard and mark the job as not discarded. |
job delete​
Delete a single job.
lab job delete <job_id>
lab job delete <job_id> --no-interactive
| Option | Description |
|---|---|
--no-interactive | Skip confirmation prompts. |
job delete-all​
Delete all jobs in the current experiment. Prompts for confirmation by default.
lab job delete-all
lab job delete-all --no-interactive
| Option | Description |
|---|---|
--no-interactive | Skip confirmation prompts. |
job publish dataset​
Publish a dataset produced by a job into the asset registry. Version label is auto-generated (v1, v2, …) when re-using an existing group.
# Publish into a new group (interactive prompts pick dataset name + group)
lab job publish dataset <job_id>
# Publish a specific named dataset into a named group
lab job publish dataset <job_id> my_dataset --group "my-dataset-group" --tag latest
# Append a new version to an existing group
lab job publish dataset <job_id> my_dataset --group "my-dataset-group" --mode existing
| Option | Description |
|---|---|
--group, -g | Registry group name (target_name). |
--mode | Publish mode: new (default) or existing. |
--tag | Version tag (default: latest). |
--description, -d | Version description. |
job publish model​
Publish a model produced by a job into the asset registry. Same shape as job publish dataset.
lab job publish model <job_id>
lab job publish model <job_id> my_model --group "my-model-group" --tag latest
lab job publish model <job_id> my_model --group "my-model-group" --mode existing
| Option | Description |
|---|---|
--group, -g | Registry group name (target_name). |
--mode | Publish mode: new (default) or existing. |
--tag | Version tag (default: latest). |
--description, -d | Version description. |
job monitor​
Launch the interactive job monitor TUI.
For human terminal use only. Not suitable for non-interactive automation or AI agents because it blocks in a full-screen TUI. For automation, use lab job list, lab job info, and lab job task-logs (optionally --follow).
lab job monitor
model​
Manage versioned model groups on the server. A group is a named collection of versions (v1, v2, …); each version points at an underlying asset (e.g. a HuggingFace model ID). Group directories are keyed by UUID, so the display name is freely editable and group lookups by name resolve to the UUID internally.
model list​
List all model groups.
lab --format json model list
model info​
Show details for a single group (by group_id or group_name).
lab --format json model info GROUP
model create​
Create a model group version. If no group with --name exists, a new group is created with version v1. If the group already exists, a new version is appended with an auto-incremented vN label (or --version-label to override).
# New group + first version (v1)
lab model create my-hf-model-id --name "My Fine-tuned Model" --description "SFT on custom data"
# Append v2 (and v3, v4, …) by re-using --name. The server scans existing
# v\d+ labels in the group and picks the next one.
lab model create my-hf-model-id-v2 --name "My Fine-tuned Model"
# Pin a specific label instead of auto-incrementing. Free-form strings are allowed
# (only the v\d+ pattern auto-increments). Collisions within a group are rejected.
lab model create my-hf-model-id-exp --name "My Fine-tuned Model" --version-label "experimental-2026-05"
| Option | Description |
|---|---|
--name | Display name for the model group (required). Re-use to append a new version. |
--description | Optional description. |
--tag | Tag to assign to this version (default: latest). Tag is moved off any prior holder in the same group. |
--version-label | Explicit label for this version. Omit to let the server auto-compute the next vN. |
model edit​
Edit a model group's display name or description.
lab model edit GROUP --name "New Name" --description "Updated description"
model upload​
Upload local files or directories into a model's storage. Creates the model entry if it doesn't exist.
lab model upload MODEL_ID ./path/to/model-dir
lab model upload MODEL_ID ./tokenizer.json ./config.json
lab model upload MODEL_ID ./path/to/model-dir --force
| Option | Description |
|---|---|
-f, --force | Overwrite server-side files that already exist. |
The upload finalizes by reading config.json from the upload root; finalization fails (cannot finalize: no config.json present) if one isn't present. Re-running upload against the same MODEL_ID skips files that already exist (exit code 2) — pass --force to overwrite.
model download​
Download a previously-uploaded model's files to <dest>/<MODEL_ID>/.
lab model download MODEL_ID ./local-models
model delete​
Delete a model group and all its versions.
lab model delete GROUP --yes
| Option | Description |
|---|---|
--yes | Skip the interactive confirmation. |
experiment​
Manage experiments. Most other commands (task, job, notes) are scoped to the default experiment in ~/.lab/config.json — change it with experiment set-default or override per-command with --experiment / -e.
experiment list​
List all experiments. Marks the current default with a * in the default column.
# All experiments
lab experiment list
# Filter by one or more tags (multiple --tag flags are AND'd)
lab experiment list --tag prod
lab experiment list --tag prod --tag eval
| Option | Description |
|---|---|
--tag NAME | Filter experiments by tag. Repeat to AND multiple tags. |
experiment create​
Create a new experiment.
lab experiment create my-experiment
lab experiment create my-experiment --set-default
| Option | Description |
|---|---|
--set-default | Set the new experiment as the default after creation. |
experiment delete​
Delete an experiment.
lab experiment delete <experiment_id>
lab experiment delete <experiment_id> --no-interactive
| Option | Description |
|---|---|
--no-interactive | Skip confirmation prompts. |
experiment set-default​
Set the default experiment used by other commands. Stored in ~/.lab/config.json.
lab experiment set-default <experiment_id>
experiment tag add / experiment tag remove​
Add or remove one or more tags on an experiment.
lab experiment tag add my-experiment prod eval
lab experiment tag remove my-experiment eval
experiment tags​
List all distinct tags across experiments you can read.
lab experiment tags
notes​
Markdown notes attached to an experiment. Stored on the server; rendered by Rich. Requires current_experiment to be set in config (or pass --experiment / -e).
notes show​
Render the current experiment's notes.
# Rendered markdown
lab notes show
# Raw markdown
lab notes show --raw
| Option | Description |
|---|---|
--raw | Print raw markdown instead of rendered output. |
notes edit​
Open the experiment's notes in $EDITOR (defaults to nano). Saves on exit.
lab notes edit
EDITOR=vim lab notes edit
notes append​
Append a line of text to the experiment's notes without opening an editor.
lab notes append "ran v3 with lr=1e-4, eval/loss=0.42"
provider​
Manage compute providers. Configuration field requirements vary by provider type; the interactive provider add flow prompts for each required field based on the selected type.
Recognised provider types: slurm, skypilot, runpod, vastai, dstack, aws, gcp, azure, local.
provider list​
List all providers.
# Only enabled providers (default)
lab provider list
# Include disabled providers
lab provider list --include-disabled
| Option | Description |
|---|---|
--include-disabled | Include disabled providers. |
provider add​
Add a new compute provider. Interactive by default — prompts for the provider type, then for the per-type config fields listed below.
# Interactive
lab provider add
# Non-interactive (requires --name, --type, --config JSON)
lab provider add --no-interactive \
--name "my-skypilot" \
--type skypilot \
--config '{"server_url":"http://127.0.0.1:46580","api_token":"..."}'
# Keep secrets out of argv (and shell history / ps listings)
lab provider add --type aws --credentials-file ./aws-creds.json
lab provider add --type gcp --credentials-file ./service-account.json
| Option | Description |
|---|---|
--name | Provider name. |
--type | One of: slurm, skypilot, runpod, vastai, dstack, aws, gcp, azure, local. |
--config JSON | Provider config as a JSON string. Required with --no-interactive. |
--interactive / --no-interactive | Use interactive prompts (default: interactive). |
--credentials-file PATH | Path to a JSON file containing provider secrets. Shape depends on --type (see below). |
Provider config fields, by --type (these are what provider add prompts for interactively, and what to put in the --config JSON object for --no-interactive):
| Type | Fields |
|---|---|
skypilot | server_url, api_token |
slurm | mode (ssh or rest), rest_url (if mode=rest), ssh_host, ssh_user, ssh_key_path, ssh_port, api_token (if mode=rest) |
runpod | api_key, api_base_url, default_gpu_type, default_region, default_template_id, default_network_volume_id |
dstack | server_url, api_token, dstack_project |
aws | region (credentials supplied via --credentials-file JSON { "aws_access_key_id": "...", "aws_secret_access_key": "..." }) |
gcp | region, zone (service account JSON supplied via --credentials-file <path-to-service-account.json>) |
azure | azure_subscription_id, azure_tenant_id, azure_client_id, azure_client_secret, azure_location |
vastai | api_key |
local | (no fields) |
For --type aws, both aws_access_key_id and aws_secret_access_key must be supplied together (either via --credentials-file or the interactive prompt). For --type gcp, a service-account JSON file is required at create time — the provider will fail its health check without it.
provider info​
Show details for a single provider.
lab provider info <provider_id>
provider update​
Update an existing provider. All option flags are optional; pass at least one.
# Rename
lab provider update <provider_id> --name "new name"
# Patch the config (merged with existing fields)
lab provider update <provider_id> --config '{"region":"us-west-2"}'
# Rotate AWS credentials without exposing them on the command line
lab provider update <provider_id> --credentials-file ./aws-creds.json
# Toggle enabled / disabled
lab provider update <provider_id> --disabled
lab provider update <provider_id> --enabled
# Toggle "team default" used when a task does not specify a provider
lab provider update <provider_id> --default
lab provider update <provider_id> --no-default
| Option | Description |
|---|---|
--name | New provider name. |
--config JSON | Config fields to merge with existing config. |
--credentials-file PATH | Path to a JSON file with provider secrets (shape depends on the provider's type). |
--disabled / --enabled | Disable or enable the provider. |
--default / --no-default | Mark / unmark this provider as the team default. |
provider check​
Run a connectivity / health check against a provider.
lab provider check <provider_id>
provider delete​
Delete a provider.
lab provider delete <provider_id>
lab provider delete <provider_id> --no-interactive
provider enable / provider disable​
Enable or disable a provider (equivalent to provider update --enabled / --disabled).
lab provider enable <provider_id>
lab provider disable <provider_id>
provider set-default / provider clear-default​
Mark or clear a provider as the team's default. The default provider is used when a task is dispatched without specifying one. Marking a provider as default automatically clears the flag from any other provider in the team.
lab provider set-default <provider_id>
lab provider clear-default <provider_id>
dataset​
Manage versioned dataset groups on the server. Mirrors the model command surface: a group is a named collection of versions; uploads create a new version under a group.
dataset list​
List all dataset groups.
lab dataset list
lab --format json dataset list
dataset info​
Show details for a single group (by group_id or group_name).
lab dataset info GROUP
dataset edit​
Edit a dataset group's display name or description.
lab dataset edit GROUP --name "New Name" --description "Updated description"
| Option | Description |
|---|---|
--name | New display name for the dataset group. |
--description | New description for the dataset group. |
dataset upload​
Upload local files or directories into a dataset on the server. Creates the dataset if it doesn't exist.
lab dataset upload DATASET_ID ./path/to/data-dir
lab dataset upload DATASET_ID ./train.jsonl ./eval.jsonl
lab dataset upload DATASET_ID ./path/to/data-dir --force
| Option | Description |
|---|---|
-f, --force | Overwrite server-side files that already exist. |
Re-running upload against the same DATASET_ID skips files that already exist (exit code 2) — pass --force to overwrite.
dataset download​
Download a dataset's files to <dest>/<DATASET_ID>/.
lab dataset download DATASET_ID ./local-data
dataset delete​
Delete a dataset group and all its versions.
lab dataset delete GROUP --yes
| Option | Description |
|---|---|
-y, --yes | Skip the interactive confirmation. |
server​
Install, run, and update the Transformer Lab Teams edition server on the local machine. These commands operate on ~/.transformerlab/.
server install​
Run the installer to generate ~/.transformerlab/.env and lay down the server source under ~/.transformerlab/src. Interactive by default.
# Interactive install
lab server install
# Preview the configuration without writing anything
lab server install --dry-run
# Install from a pre-written .env config file (skips prompts)
lab server install --config ./my-config.env
| Option | Description |
|---|---|
--dry-run | Show configuration without writing any files. |
--config PATH | Path to a .env config file. Skips interactive prompts and installs from this file. |
Do not run server install from inside ~/.transformerlab/src — that directory is deleted during installation. Change to a different directory first (cd ~ && lab server install).
server version​
Show the installed server version and check PyPI for a newer release.
lab server version
lab --format json server version
server start​
Start the local server (defaults to port 8338). Runs in the background by default; logs to ~/.transformerlab/server.log.
lab server start
lab server start --port 9000
lab server start --foreground
| Option | Description |
|---|---|
--port | Port to start the server on (default: 8338). |
--foreground | Run in the foreground instead of background. |
server stop​
Stop the local server.
lab server stop
lab server stop --port 9000
lab server stop --force # SIGKILL instead of SIGTERM
| Option | Description |
|---|---|
--port | Port the server is running on (default: 8338). |
--force, -f | Force kill (SIGKILL) instead of graceful shutdown. |
server restart​
Stop the server (graceful, with SIGKILL fallback) and start it again on the same port.
lab server restart
lab server restart --port 9000
server update​
Update an existing server installation to the latest published version (runs the install script again, preserving config).
lab server update