Workout CLI: Command-Line Workout Logger with Strength Progression Analysis

Why Do I Need a Command-Line Workout Log?

To be honest, I've tried various fitness apps before—Strong, Hevy, FitNotes, you name it. But every time I unlocked my phone, opened the app, found the exercise, and typed in the numbers, it felt like a scramble. Especially during rest intervals, which are only a few minutes long—tapping away on the screen was really annoying. Then I discovered Workout CLI, a pure command-line training log tool, and it felt like a whole new world opened up!

Workout CLI is a terminal-based fitness logging tool. You don't need to open any graphical interface; just type workout start push directly in the command line to begin a push session. Then, use workout log bench-press 135 8 to log one set of bench press (135 lbs, 8 reps). When you're done, enter workout done to save everything. It even automatically calculates your personal records (PRs), weekly training volume, and strength progression curves—all data is stored locally, with no ads, no subscriptions, and super clean.

Installation & Configuration: One Minute to Get Started

First, you need to run in your terminal (assuming Node.js and npm are already installed):

npx skills add https://github.com/rustykuntz/rocie-tools --skill workout

This command pulls the workout skill package from the rusty kuntz rocie-tools repository. After installation, you can use the workout command. If you get an error saying the command is not found, check if your npm package path is in the PATH variable.

Next, create a personal configuration file—because Workout CLI supports multiple users. You and your training partner can use the same terminal but with separate configurations, without interfering with each other:

workout profile create sarah
workout profile list

If you're the only user, you don't need to specify the --profile parameter; it defaults to the current user. However, once you have multiple profiles, you must add --profile yourname before each command, for example: workout --profile mike log bench-press 185 8.

Core Operations: Master These Four Moves

After tinkering for a few days, I've summarized the most commonly used four steps:

• Start a workout: workout start --empty starts a free session, or use a template like workout start push to directly load a previously created push template.
• Log sets: workout log bench-press 135 8 logs one set. To log multiple sets at once, write: workout log bench-press 135 8,8,7 (meaning three sets, all with weight 135, reps 8, 8, 7 respectively).
• Add notes: Use workout note to add some context, such as "left elbow a bit sore today" or "used narrow grip." Note: notes cannot replace real data—weights and reps must be recorded accurately!
• End or cancel: When done, enter workout done to save. If you want to discard the session halfway, use workout cancel to throw it all away.

There's also a cool trick: workout swap bench-press db-bench replaces all barbell bench press records in the current session with dumbbell bench press, perfect for when you switch exercises mid-session.

Hardcore Details: Accuracy is Key

The designers of Workout CLI emphasized one point: sets must record the real numbers. Do you think you can log 0 lbs and then write a note saying "actually used 50 lbs"? No! That would completely distort the PR and volume statistics. The correct approach is: if you're unsure about the exact weight, clarify it before logging. Also, any new exercise must first be added to the library, otherwise it cannot be logged. For example, if you want to do "Dumbbell RDL" and it's not in the library, you first:

workout exercises add "Dumbbell RDL" --muscles hamstrings,glutes --type compound --equipment dumbbell

Adding an exercise to the library requires three mandatory parameters: --muscles (target muscles, separated by commas), --type (compound or isolation), and --equipment (optional: barbell, dumbbell, cable, etc.).

If you make a mistake during the session, you can use workout undo to undo the last set, or workout undo bench-press to undo only the last set of a specific exercise. More powerful is workout edit bench-press 2 155 8 to directly modify the weight and reps of the second set, or workout delete bench-press 3 to delete the third set. These commands are all 1-indexed, making them intuitive to use.

Data Analysis: See Your Progress

Logging without analyzing is pointless. Workout CLI provides a series of commands to view statistics:

• Last workout: workout last shows the content of the previous training session.
• Exercise history: workout history bench-press displays all historical records of bench press.
• Personal records: workout pr lists all your personal records for every exercise.

Additionally, you can view weekly volume: workout volume shows the total volume for the current week. For a more detailed breakdown, use workout volume --week 2024-03 to specify a particular week. You can also generate a strength curve: workout curve bench-press outputs a simple text-based chart showing how your 1RM (estimated one-rep max) has changed over time.

If you want to export your data, workout export csv creates a CSV file with all your logged sessions, which you can then import into a spreadsheet or analysis tool. All data is saved in ~/.workout/data/ as JSON files, so you can also back them up or manipulate them directly.

Advanced Features: Automate Your Logging

For power users, Workout CLI supports scripting and aliases. For instance, you can create a shell alias:

alias wl="workout --profile sarah log"
alias ws="workout --profile sarah start"
alias wd="workout --profile sarah done"

Then you can log a set with just wl deadlift 315 5. You can also chain commands: workout start push && workout log bench-press 135 8 && workout done runs everything in one line—useful for simple sessions.

Another pro tip: use the --no-save flag to simulate a log without actually saving, perfect for testing before committing. For example: workout --no-save log squat 225 5 will check if the exercise exists and validate the data, but won't store anything.

FAQ and Troubleshooting

• Command not found after installation? Make sure npm global packages are in your PATH. Try npm list -g --depth=0 to see if @skills/workout is installed. If not, re-run the npx skills add command.
• How do I update the exercise library? Use workout exercises list to see all exercises. To update an exercise, use workout exercises edit "exercise-name" --muscles ....
• Can I share my data with a friend? Yes, you can copy the ~/.workout/ directory to another machine, but be aware that profiles and data are separate per user.
• I accidentally deleted a session. Can I recover it? Workout CLI does not have an undo for deleted sessions, but if you have backups of the JSON files, you can restore them manually.

Overall, Workout CLI is a minimalist but powerful tool for those who spend most of their time in the terminal. It's fast, private, and respects your data. Once you get used to the command-line flow, you'll never want to go back to tapping on a phone screen.

So, if you're tired of bloated fitness apps and want complete control over your workout logs, give Workout CLI a try. It's free, open-source, and runs anywhere Node.js can. Start tracking your gains the terminal way!