cli-usage

name	cli-usage
description	Use when invoking training, evaluation, and dataset preparation via CLI. Provides all standard commands for this project.
triggers	["train model","run training","evaluate","download dataset","cli commands","modal"]

Skill: cli-usage

This skill covers all CLI commands for operating the tiny-cats-model project.

Setup

# Install dependencies
pip install -r requirements.txt

# Download and prepare dataset
bash data/download.sh
# Dataset will be at: data/cats/cat/ and data/cats/other/

Training

# Basic training (10 epochs, resnet18)
python src/train.py data/cats

# Custom training
python src/train.py data/cats \
  --epochs 20 \
  --batch-size 64 \
  --lr 0.0001 \
  --backbone resnet34 \
  --output my_model.pt

# Training without pretrained weights
python src/train.py data/cats --no-pretrained

Evaluation

# Evaluate with default settings
python src/eval.py

# Evaluate with custom checkpoint
python src/eval.py \
  --data-dir data/cats \
  --checkpoint cats_model.pt \
  --backbone resnet18

Testing

# Run all unit tests
pytest tests/ -v

# Run with coverage
pytest tests/ -v --cov=src --cov-report=term-missing

Linting & Formatting

# Lint
ruff check .
flake8 . --max-line-length=88

# Auto-fix lint issues
ruff check . --fix

# Format code
black .

# Check formatting without modifying
black --check .

Modal GPU Training (Modal 1.0+)

# Set credentials globally (Modal 1.0+ uses 'token new')
modal token new

# Run training on GPU
modal run src/train.py

# Run with custom options
modal run src/train.py --epochs 20 --batch-size 64

Modal best practices

• Modal timeout is 24h per function call. Our scripts comply (3600 s for classifier, 86400 s = 24 h for DiT). For runs > 24h, design as reentrant + use --detach.
• Always call volume.commit() after writing a checkpoint volume. We do this in both train.py and train_dit.py.
• modal token new is the canonical auth command. The old modal token set (Modal 0.x) no longer works.
• The live per-iteration Speed: 2.2 steps/s printed by the trainer reflects GPU forward+backward only — wall-clock between step reports includes container cold-start, image pull, dataset download, and per-iteration volume/ONNX overhead. See plans/ADR-057-modal-cli-verification-and-best-practices-2026.md for the full breakdown.
• When triggering from GitHub Actions, prefer reusing a running run over cancelling/re-triggering — every re-trigger pays container cold-start + image-pull cost.

Full Verification

# Run complete CI check suite
bash .agents/skills/testing-workflow/verify.sh

# Or use the quality gate
bash .agents/skills/git-workflow/quality-gate.sh

# Or use the new scripts
bash scripts/quality-gate.sh

Command Reference

Task	Command
Install	pip install -r requirements.txt
Dataset	bash data/download.sh
Train	python src/train.py data/cats
Evaluate	python src/eval.py
Tests	pytest tests/ -v
Lint	ruff check . && flake8 .
Format	black .
CI verify	bash .agents/skills/testing-workflow/verify.sh