tinker-cli

name	tinker-cli
description	Guide for the Tinker CLI — managing training runs, checkpoints, downloading weights, and publishing to HuggingFace. Use when the user asks about CLI commands, listing runs, managing checkpoints from the terminal, or uploading to HF Hub.

Tinker CLI

The tinker CLI is installed with the Tinker Python SDK. It provides commands for managing training runs and checkpoints from the terminal.

Requires TINKER_API_KEY environment variable to be set.

Global options

tinker --format table   # Rich table output (default)
tinker --format json    # JSON output (for scripting)

Training runs

# List recent training runs
tinker run list
tinker run list --limit 50

# Show details for a specific run
tinker run info <RUN_ID>

# Custom columns
tinker run list --columns id,model,lora,updated,status,checkpoint

Available columns: id, model, owner, lora, updated, status, checkpoint, checkpoint_time.

Checkpoints

List and inspect

# List checkpoints for a specific run
tinker checkpoint list --run-id <RUN_ID>

# List all your checkpoints across runs
tinker checkpoint list
tinker checkpoint list --limit 50

# Show checkpoint details
tinker checkpoint info <TINKER_PATH>

Download

# Download and extract a checkpoint
tinker checkpoint download <TINKER_PATH>
tinker checkpoint download <TINKER_PATH> --output ./my-adapter
tinker checkpoint download <TINKER_PATH> --force  # Overwrite existing

Visibility

# Make a checkpoint publicly accessible
tinker checkpoint publish <TINKER_PATH>

# Make a checkpoint private
tinker checkpoint unpublish <TINKER_PATH>

TTL (expiration)

# Set checkpoint to expire in 24 hours
tinker checkpoint set-ttl <TINKER_PATH> --ttl 86400

# Remove expiration (keep indefinitely)
tinker checkpoint set-ttl <TINKER_PATH> --remove

Delete

# Delete checkpoints (with confirmation prompt)
tinker checkpoint delete <TINKER_PATH>

# Delete without confirmation
tinker checkpoint delete <TINKER_PATH> -y

# Delete multiple
tinker checkpoint delete <PATH1> <PATH2> <PATH3>

Upload to HuggingFace Hub

# Push checkpoint to HuggingFace
tinker checkpoint push-hf <TINKER_PATH> --repo user/my-model

# Push as public repo
tinker checkpoint push-hf <TINKER_PATH> --repo user/my-model --public

# Advanced options
tinker checkpoint push-hf <TINKER_PATH> \
    --repo user/my-model \
    --revision main \
    --commit-message "Upload fine-tuned model" \
    --create-pr \
    --no-model-card

Options: --repo, --public, --revision, --commit-message, --create-pr, --allow-pattern, --ignore-pattern, --no-model-card.

Version

tinker version   # e.g. "tinker 0.15.0"

Common patterns

Script-friendly output

# Get checkpoint paths as JSON for scripting
tinker checkpoint list --format json | jq '.[].tinker_path'

# Get run IDs
tinker run list --format json | jq '.[].id'

Typical workflow

# 1. Find your training run
tinker run list

# 2. List checkpoints for that run
tinker checkpoint list --run-id <RUN_ID>

# 3. Download the final checkpoint
tinker checkpoint download tinker://<RUN_ID>/sampler_weights/final -o ./adapter

# 4. Or push directly to HuggingFace
tinker checkpoint push-hf tinker://<RUN_ID>/sampler_weights/final --repo user/my-model

Common pitfalls

• TINKER_API_KEY must be set — the CLI reads it from the environment
• Checkpoint paths use the format tinker://<run-id>/<type>/<checkpoint-id>
• push-hf uploads the raw checkpoint — for merged HF models, use weights.build_hf_model() in Python first (see /weights skill)
• delete is permanent and irreversible — use -y flag carefully