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