workout

name: workout description: Track workouts, log sets, manage exercises and templates with workout-cli. Supports multi-user profiles. Use when helping users record gym sessions, view history, or analyze strength progression. metadata: {"clawdbot":{"emoji":"🏋️","requires":{"bins":["workout"]}}}

Workout CLI

CLI for tracking workouts, managing exercises, and analyzing training progress.

Installation

curl -fsSL https://raw.githubusercontent.com/gricha/workout-cli/main/install.sh | bash

Then add to PATH: export PATH="$HOME/.workout-cli/bin:$PATH"

Quick Reference

Multi-User Profiles

Multiple people can track workouts independently using profiles.

# List all profiles
workout profile list

# Create a new profile
workout profile create sarah

# Delete a profile
workout profile delete old-profile

When multiple profiles exist, specify which one:

workout --profile mike start push-day
workout --profile mike log bench-press 185 8
workout --profile mike done

• Single profile: Commands work without --profile (backwards compatible)
• Shared exercises: Exercise library is shared across all profiles
• Per-user data: Templates, workouts, config, and current session are per-profile

Workout Sessions

Start a Workout

# Freestyle session (most common)
workout start --empty

# From template
workout start push-day

# Resume interrupted
workout start --continue

Log Sets

# Multiple sets at same weight
workout log bench-press 135 8,8,7,6

# Progressive weights (call multiple times)
workout log squat 135 10
workout log squat 185 8
workout log squat 225 5,5,5

# Relative to last session
workout log deadlift +10 5

# With RIR tracking
workout log bench-press 185 8 --rir 2

Notes

# Session-level note
workout note "Elbow felt tight on pulling movements"

# Exercise-specific note
workout note lat-pulldown "Dropped weight due to elbow"

Swap & Add

# Swap an exercise (moves logged sets to new exercise)
workout swap bench-press dumbbell-bench-press

# Add exercise mid-workout
workout add face-pulls

Finish or Cancel

# Complete and save
workout done
# Shows: duration, total sets, volume, muscles worked

# Discard without saving
workout cancel

Check Status

workout status
# Shows current exercises, sets logged, and notes

Undo, Edit & Delete Sets

Fix mistakes during a workout without canceling:

# Remove last logged set (any exercise)
workout undo

# Remove last set of specific exercise
workout undo bench-press

# Edit set 2: change weight and reps
workout edit bench-press 2 155 8

# Edit set with options
workout edit bench-press 2 --reps 10 --rir 2

# Delete set 3 entirely
workout delete bench-press 3

Set numbers are 1-indexed.

Exercise Library

List Exercises

workout exercises list
workout exercises list --muscle chest
workout exercises list --type compound

Add Custom Exercise

⚠️ All three options required:

workout exercises add "Bayesian Cable Curl" \
  --muscles biceps \
  --type isolation \
  --equipment cable

workout exercises add "Single Arm Cable Row" \
  --muscles back,lats \
  --type compound \
  --equipment cable

Show/Edit/Delete

workout exercises show bench-press
workout exercises edit bench-press --notes "Pause at bottom"
workout exercises delete my-custom-exercise

Templates

# List templates
workout templates list

# Create template
workout templates create "Push Day" \
  -e "bench-press:4x8-12, overhead-press:3x8-10, lateral-raise:3x12-15"

# Show template
workout templates show push-day

# Delete template
workout templates delete push-day

History & Analytics

Last Workout

workout last
workout last --full

Exercise History

workout history bench-press
workout history squat --last 20

Personal Records

workout pr
workout pr bench-press
workout pr --muscle chest

Shows weight × reps with estimated 1RM.

Volume Analysis

workout volume              # Last 4 weeks
workout volume --week
workout volume --month
workout volume --by muscle
workout volume --by exercise

Progression

workout progression bench-press
# Shows: date, best set, estimated 1RM, volume over time

Typical Session

# 1. Start
workout start --empty

# 2. Log as you go
workout log lat-pulldown 100 10,10,9,8
workout note lat-pulldown "Dropped from 120 due to elbow"
workout log single-arm-cable-row 40 12,12,10
workout log single-arm-cable-row 45 10,10

# 3. Add session notes
workout note "Pull day - elbow still recovering"

# 4. Finish
workout done

Data Storage

~/.workout/
  exercises.json   # Exercise library
  workouts/        # Completed sessions

JSON Output

All commands support --json:

workout pr --json
workout last --json
workout history squat --json

Gotchas

• exercises add requires all three: --muscles, --type, --equipment
• Weights are in lbs by default
• Multiple calls to log at different weights work fine (common pattern)
• swap moves all logged sets to the new exercise
• note <exercise> <text> adds note to specific exercise; note <text> adds session note

References

• Repository: https://github.com/gricha/workout-cli