LIFT(1)

NAME
lift - bodybuilding workout tracker CLI

SYNOPSIS
lift [--db-path PATH] [--help] [--version] COMMAND [OPTIONS] [ARGS]

DESCRIPTION
lift is a robust, feature-complete command-line interface for tracking weightlifting sessions with a focus on bodybuilding and progressive overload.

LIFT provides a comprehensive suite of tools for tracking exercises, logging workouts, managing training programs, analyzing performance statistics, tracking body measurements, and managing workout data.

The application uses DuckDB for high-performance analytical queries and stores all data locally in a single database file.

GLOBAL OPTIONS

--db-path PATH
    Specify a custom database path. Default: ~/.lift/lift.duckdb

--help
    Show help message and exit.

--version
    Show program version and exit.

COMMANDS

  Database Management

init
    Initialize the database and load seed data (137 exercises).

    --force
        Force reinitialization of an existing database.

info
    Display database information and table statistics.

version
    Display version information.

  Exercise Management

exercises list
    List all exercises with optional filtering.

    --category CATEGORY
        Filter by category (Push, Pull, Legs, Core).

    --muscle MUSCLE
        Filter by primary muscle group.

    --equipment EQUIPMENT
        Filter by equipment type.

    --summary
        Show summary statistics instead of full list.

exercises search
    QUERY Search exercises by name.

exercises info
    NAME Display detailed information about a specific exercise.

exercises stats
    Show exercise library statistics.

exercises add
    Add a custom exercise (interactive).

exercises delete
    NAME Delete a custom exercise.

    --force
        Skip confirmation prompt.

  Workout Tracking

workout start
    Start an interactive workout session.

    --name NAME
        Name for the workout session.

    --program PROGRAM
        Start workout from a program template.

    During a workout session, log sets using shortcuts:

        185 10
            185 lbs × 10 reps

        185 10 8.5
            185 lbs × 10 reps @ RPE 8.5

        s   Same as previous set

        +5  Add 5 lbs to previous weight

        -5 8
            Subtract 5 lbs, 8 reps

        done
            Finish current exercise

workout last
    Display details of the last workout.

workout history
    Show workout history.

    --limit N
        Limit number of workouts shown (default: 10).

workout show
    WORKOUT_ID Display detailed information about a specific workout.

workout delete
    WORKOUT_ID Delete a workout.

    --force
        Skip confirmation prompt.

  Program Management

program create
    Create a new training program (interactive).

program list
    List all training programs.

program show
    NAME Display detailed program information.

program activate
    NAME Set a program as active.

program clone
    SOURCE DESTINATION Clone an existing program.

program delete
    NAME Delete a program.

    --force
        Skip confirmation prompt.

program import-samples
    Import sample programs (PPL 6-Day, Upper/Lower 4-Day, Full Body 3-Day).

  Statistics & Analytics

stats summary
    Show training summary.

    --week
        Show weekly summary.

    --month
        Show monthly summary.

stats exercise
    NAME Show statistics for a specific exercise.

    --chart
        Display progression chart.

stats volume
    Analyze training volume.

    --weeks N
        Number of weeks to analyze (default: 4).

stats pr
    Show personal records.

    --exercise NAME
        Show PRs for specific exercise.

stats muscle
    MUSCLE Analyze volume for a specific muscle group.

stats streak
    Show current training streak.

stats progress
    EXERCISE Show detailed progression for an exercise.

    --chart
        Display progression chart.

  Body Tracking

body weight
    WEIGHT Log bodyweight.

    --unit UNIT
        Weight unit (lbs or kg).

body measure
    Log full body measurements (interactive).

body history
    View measurement history.

    --measurement NAME
        Specific measurement (weight, chest, waist, etc.).

    --weeks N
        Number of weeks to show (default: 12).

    --limit N
        Maximum number of entries (default: 20).

body progress
    Show progress comparison.

    --weeks N
        Compare with N weeks ago (default: 4).

body chart
    MEASUREMENT Display terminal chart for a measurement.

    --weeks N
        Number of weeks to chart (default: 12).

body latest
    Show most recent measurements.

  Data Management

data export
    Export data from database.

    --format FORMAT
        Export format: csv or json (default: json).

    --table TABLE
        Specific table to export (omit for all tables).

    --output PATH
        Output file or directory path.

data import
    FILE Import data from a file.

    --table TABLE
        Target table name (required for CSV).

data backup
    Create a database backup.

    --output PATH
        Backup directory path.

data restore
    PATH Restore database from backup.

    --force
        Skip confirmation prompt.

data optimize
    Optimize database for better performance.

  Configuration

config list
    List all configuration settings.

config get
    KEY Get a configuration value.

config set
    KEY VALUE Set a configuration value.

config reset
    Reset configuration to defaults.

    --force
        Skip confirmation prompt.

CONFIGURATION SETTINGS

default_weight_unit
    Default weight unit: lbs or kg (default: lbs)

default_measurement_unit
    Default measurement unit: in or cm (default: in)

enable_rpe
    Enable RPE (Rate of Perceived Exertion) tracking (default: true)

enable_tempo
    Enable tempo tracking (default: false)

rest_timer_default
    Default rest timer in seconds (default: 90)

auto_detect_pr
    Automatically detect personal records (default: true)

EXAMPLES

  Initialize and Start Using LIFT

    # Initialize the database
    $ lift init
    # Start your first workout
    $ lift workout start
    # List available exercises
    $ lift exercises list
    # Search for bench press variations
    $ lift exercises search bench

  Log a Workout Session

    $ lift workout start --name "Push Day"
    # The interactive session will prompt you:
    Exercise: bench press
    Set 1 > 185 10 8
    ✓ 185 lbs × 10 reps @ RPE 8.0
    Set 2 > s
    ✓ 185 lbs × 10 reps @ RPE 8.0
    Set 3 > +5 8 9
    ✓ 190 lbs × 8 reps @ RPE 9.0
    Set 4 > done
    Exercise: overhead press
    # ... continue logging

  View Statistics and Progress

    # Show personal records
    $ lift stats pr
    # View progression for a specific exercise
    $ lift stats exercise "Bench Press" --chart
    # Check weekly training summary
    $ lift stats summary --week
    # View training streak
    $ lift stats streak

  Manage Training Programs

    # Import sample programs
    $ lift program import-samples
    # List available programs
    $ lift program list
    # View program details
    $ lift program show "PPL 6-Day"
    # Activate a program
    $ lift program activate "PPL 6-Day"
    # Start workout from active program
    $ lift workout start

  Track Body Measurements

    # Log bodyweight
    $ lift body weight 185.5
    # Log full measurements (interactive)
    $ lift body measure
    # View weight history
    $ lift body history --measurement weight --weeks 12
    # Display weight chart
    $ lift body chart weight --weeks 8
    # Compare progress
    $ lift body progress --weeks 4

  Export and Backup Data

    # Export all data to JSON
    $ lift data export --format json --output my_workouts.json
    # Export workouts table to CSV
    $ lift data export --format csv --table workouts --output workouts.csv
    # Create a backup
    $ lift data backup --output ~/backups/lift_backup
    # Restore from backup
    $ lift data restore ~/backups/lift_backup

  Configure LIFT

    # View all settings
    $ lift config list
    # Change to metric units
    $ lift config set default_weight_unit kg
    $ lift config set default_measurement_unit cm
    # Enable tempo tracking
    $ lift config set enable_tempo true
    # Set default rest timer to 2 minutes
    $ lift config set rest_timer_default 120

  Use Custom Database Location

    # Initialize database in custom location
    $ lift --db-path ~/my_workouts.duckdb init
    # Use custom database for commands
    $ lift --db-path ~/my_workouts.duckdb workout start
    # Set via environment variable
    $ export LIFT_DB_PATH=~/my_workouts.duckdb
    $ lift workout start

ENVIRONMENT

LIFT_DB_PATH
    Path to the database file. Overrides the default (~/.lift/lift.duckdb) but is overridden by --db-path.

FILES

~/.lift/lift.duckdb
    Default database file location.

~/.lift/lift.duckdb.wal
    Write-Ahead Log (WAL) file for the database.

DATABASE SCHEMA
The database includes the following main tables:

exercises
    Exercise library with 137 pre-loaded exercises and custom exercises.

workouts
    Workout session records with date, duration, and notes.

sets
    Individual set logs with weight, reps, RPE, and tempo.

programs
    Training program definitions.

program_workouts
    Workout templates within programs.

program_exercises
    Exercise prescriptions with target sets, reps, and RPE.

personal_records
    Personal record tracking (1RM, 3RM, 5RM, 10RM, volume).

body_measurements
    Body measurement and tracking data.

settings
    Application configuration settings.

The database also includes analytical views for efficient querying: workout_volume, weekly_muscle_volume, exercise_progression, bodyweight_trend.

EXERCISE CATEGORIES

Push
    Pressing movements (bench press, overhead press, dips, etc.)

Pull
    Pulling movements (rows, pull-ups, deadlifts, curls, etc.)

Legs
    Lower body exercises (squats, leg press, lunges, leg curls, etc.)

Core
    Core and abdominal exercises (planks, crunches, leg raises, etc.)

MUSCLE GROUPS
Chest, Back, Shoulders, Triceps, Biceps, Forearms, Quads, Hamstrings, Glutes, Calves, Abs, Obliques, Lower Back

EQUIPMENT TYPES
Barbell, Dumbbell, Cable, Machine, Bodyweight, Bands, Kettlebell, Smith Machine

EXIT STATUS

0   Successful execution

1   General error (invalid input, database error, etc.)

NOTES

  Progressive Overload
LIFT automatically tracks your progression and can detect when you've achieved new personal records. The system uses multiple 1RM calculation formulas to estimate your strength levels.

  RPE (Rate of Perceived Exertion)
RPE is a subjective measure of how difficult a set felt, on a scale typically from 1-10. An RPE of 8 means you could have done 2 more reps before failure.

  Database Performance
The database is optimized for analytical queries. Running lift data optimize periodically can help maintain performance with large datasets.

BUGS
Report bugs at: https://github.com/parkerdgabel/lift/issues

AUTHOR
Written by Parker Gabel.

COPYRIGHT
Copyright © 2025 Parker Gabel. License: MIT
This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law.

SEE ALSO
Full documentation: https://github.com/parkerdgabel/lift

Related tools: sqlite3(1), duckdb(1)