Table of Contents

1. Installation
   1. uv
   2. pipx
2. Usage
   1. Initialize
   2. Update Exercises
   3. Commands
      1. save
      2. random
      3. last
      4. view
      5. stats

kettlebells is a CLI designed to create, save, and track the progress of kettlebell workouts. The inspiration for this project came from Pat Flynn’s conversation with Bret Jones. (For a more detailed look at Iron Cardio, go checkout the Iron Cardio Book by Bret Jones.) After starting an initial project that focused only on iron cardio, I wanted to be able to add more. This is essentially a fork of the iron-cardio project designed to add various workouts such as the armor building complex, and dry fighting weight.

As of version 0.2.1, the way workouts are constructed has completely changed. This will allow users to construct their own custom workouts in the future. It will also allow the stats to keep track of how many reps of each type of exercise have been done.

Installation

uv

uv tool install kettlebells

pipx

pipx install kettlebells

Usage

Initialize

Run the init command to create the database.

kettlebells init

Next, run the setloads command. This sets the units to either pounds (lbs) or kilograms (kg), the user’s bodyweight, and the loads for the light, medium, and heavy kettlebell. This command can be run as needed when the user is ready to move up in load or bodyweight changes.

kettlebells setloads

Update Exercises

Occasionally, new exercises are added to the database. If you have already initialized in a previous version, run the update command.

kettlebells update

Commands

save

The save command saves workouts to the database. The current options are:

• ic
• abc
• btb
• dfw
• pw
• rop
• wolf
• custom

When run with no option, the save command will attempt to use the most recently generated random workout. Otherwise, use the --workout-type option to manually enter a workout, e.g.:

kettlebells save --workout-type abc

1. dfw

   When the save command is run with the workout type of dfw, a dry fighting weight workout is saved. See the original post for more details

   kettlebells save --workout-type dfw
   

2. btb

   The save command with a workout type of btb allows the user to save a Back to Basics Workout. These workouts are constructed based on The Pat Flynn Show episode with Dan John The BEST Kettlebell Program for GEGINNERS | THE BTBKP. The choices are ladders of 2-3-5 clean and presses followed by either snatches or double front squats. The warm up and cool exercises are not included in the workout.

   kettlebells save --workout-type btb
   

   The program options are:

   First block	Second Block
   2 ladders	60 Snatches
   3 ladders	80 Snatches
   5 ladders	100 Snatches
   2 ladders	10 sets of 5 Double Front Squats
   3 ladders	10 sets of 5 Double Front Squats
   5 ladders	10 sets of 5 Double Front Squats

3. pw

   The save command with a workout type of pw saves versions of Dan John’s Perfect Workout. While in the video Dan does hip thrusts until it burns, for ease of recording the workout, kettlebells offers a set number of reps for the hip thrust.

   kettlebells save --workout-type pw
   

   The program options are:

   Variation	Exercises	Sets	Reps
   Original	Half-kneeling Press	3	8
   	Hanging Leg Raise	3	8
   	Banded Hip Thrust	3	15
   	Bulgarian Goat Bag Swing	3	8
   	Goblet Squat / Broomstick Overhead Squat	1	8
   Indoor	Half-kneeling Press	3	8
   	Child’s Pose	3	20 secs
   	Hip Thrust / Clam Shell (15, 14, 13…)	1	120
   	Goblet Squat / Broomstick Overhead Squat	1	8
   The Bull	Half-kneeling Press	3	8
   	Hanging Leg Raise	3	8
   	Bulgarian Goat Bag Swing	3	8
   	Bent Over Rows	3	8
   	Goblet Squat / Broomstick Overhead Squat	1	8

4. rop

   The save command with a workout type of rop saves versions of Pavel Tsatsouline’s rite of passage program from Enter The Kettlebell. The clean and press and pullups are calculated as ladders, while the swings and snatches are straight sets.

   kettlebells save --workout-type rop
   

5. wolf

   The save command with a workout type of wolf saves workouts from the free program The Wolf from Geoff Neupert. This is a gasser for sure.

   kettlebells save --workout-type wolf
   

6. custom

   When the save command is run with the workout type of custom, the user can save a custom workout. Custom workouts need a workout_type and a variation. The default is custom. Exercises are chosen via iterfzf. Select Other to add a custom exercise. Select Done or press escape when finished adding all the exercises.

   kettlebells save --workout-type custom
   

   1. Reps and Loads for Custom Exercises

      Unilateral exercises such as the single arm overhead press (simply “Press” in the program) should have the reps doubled. For example, if the set and rep scheme is 3 sets of 8 single arm overhead presses on the left and right arm, that should be saved as 16 reps per set for that exercise.

      When the stats are calculated, any exercise that has “Double” in it has the load multiplied by 2. So Double Pressing a pair of 24 kg kettlebells should be saved as a load of 24 kg, but the calculations will result in 48 kg per rep. If using uneven sized bells, use the average weight of the two bells rounded to the nearest integer.

   2. Suggested Use for Complexes

      Consider a workout out like the 8 - 5 - 3 Rep Scheme from Pat Flynn. The workout_type would be “complex”, the variation would be “8-5-3 Rep Scheme”. Technically, a set consists of 8 Goblet Squats, 5 Start Stop Swings, 3 Push-ups. Then you would repeat this for 5 rounds. However, in kettlebells the user will add each exercise separately. So the Goblet Squat would be 5 sets of 8. The Start Stop Swing would be 5 sets of 5, and the Push-up would be 5 sets of 3.

random

The work out command generates a random workout. The current options are:

• ic (Iron Cardio)
• abc (Armor Building Complex)

1. iron-cardio

   The random command with a workout type of ic, generates a random iron cardio workout.

   kettlebells random --workout-type ic
   

   Iron cardio workouts are built from the following parameters:

   Parameter	Options
   Single Bell Variations	Classic
   	Classic + Pull-up
   	Classic + Snatch
   	Traveling 2s
   Double Bell Variations	Double Classic
   	Double Classic + Pull-up
   	Double Traveling 2s
   TIMES	30 mins
   	20 mins
   	10 mins
   LOADS	heavy
   	medium
   	light
   SWINGS	0 - 150

2. abc

   The random command with a workout type of abc will generate a random armor building complex workout.

   kettlebells random --workout-type abc
   

   Parameter	Options
   Single Bell Variations	Armor Building Complex 2.0
   Double Bell Variations	Armor Building Complex
   TIMES	30 mins
   	25 mins
   	20 mins
   	15 mins
   	10 mins
   LOADS	heavy
   	medium
   	light
   SWINGS	0 - 100

last

The last command displays the last saved workout and calculates the stats for it.

kettlebells last

view

Use the view command to search for previous workouts by date. If you have ripgrep installed, use the --preview flag to view more information about the workout based on the date.

kettlebells view --preview

Use the --Program flag to filter workouts based on a certain workout_type.

kettlebells view --Program

stats

The stats command displays the aggregated workout count, time, weight moved, number of reps, and density for all workout in the database.

kettlebells stats

1. Filtering by time

   The stats command can be filtered using three arguments: --start, --end, --year.

   Here is an example using --start and --end to get the stats from Jan 2024.

   kettlebells stats --start 2024-01-01 --end 2024-02-01
   

   If you want to see an entire year, just use --year.

   kettlebells stats --year 2024
   

   All three time filters work with the plots. And --year works with the calendar command covered later.

2. plot

   To display a line plot of the weight moved per workout, use the --plot line option. Add a line at the median with --median or at the mean with --average.

   kettlebells stats --plot line
   

   To display a horizontal bar plot grouped by month, use the --plot bar option.

   kettlebells stats --plot bar
   

   To display an event plot of the current year, use the --plot event option.

   kettlebells stats --plot event
   

3. calendar

   To display a calendar of workouts in a given year, use the --calendar flag and pass the year as the argument.

   kettlebells stats --calendar -y 2023
   

4. best

   The best command displays the top ten workout based on the weight moved.

   kettlebells stats --best
   

   Use the --sort option to sort the table by:

   • weight-moved (default)
   • reps
   • weight-density
   • rep-density
   • time