@profullstack/fasting
Advanced tools
A comprehensive CLI and Node.js module for 16:8 intermittent fasting with meal tracking, weight monitoring, and fast history with visual charts
A comprehensive CLI and Node.js module for 16:8 intermittent fasting with meal tracking, weight monitoring, fast history, and AI-powered personalized recommendations with visual charts.
pnpm install -g @profullstack/fasting
fasting setup
pnpm install
pnpm link --global
fasting setup
The setup command will prompt you for your OpenAI API key, unit system preference (imperial/metric), timezone, activity level, and medical conditions, saving them securely to ~/.config/fasting/config.json.
Alternative: You can also set the OPENAI_API_KEY environment variable if you prefer.
fasting setup --supabase
This will prompt you for your Supabase configuration and enable cloud storage for your data.
To run the CLI locally during development:
# Option 1: Direct execution
node bin/cli.js summary
node bin/cli.js fast start
node bin/cli.js meal "Chicken salad" --calories 350
# Option 2: After linking globally
pnpm link --global
fasting summary
fasting fast start
# Option 3: Using pnpm exec
pnpm exec fasting summary
# Start a fast (uses current time)
fasting fast start
# Start a fast at a specific time
fasting fast start --time "18:00"
fasting fast start --time "2023-12-01 18:00"
# End a fast (uses current time)
fasting fast end
# End a fast at a specific time
fasting fast end --time "10:00"
# Calories are automatically estimated using AI with unit-aware prompts
fasting meal "Grilled chicken breast with quinoa"
fasting drink "Orange juice"
# Specify portion sizes for more accurate estimates (supports both imperial and metric)
fasting meal "Pizza" --size "2 slices"
fasting drink "Orange juice" --size "32oz" # Imperial
fasting drink "Orange juice" --size "500ml" # Metric
fasting meal "Chicken breast" --size "6oz" # Imperial
fasting meal "Chicken breast" --size "150g" # Metric
fasting meal "Salad" -s "large"
# Set your activity level for personalized recommendations
fasting activity sedentary # Little to no exercise, desk job
fasting activity moderate # Light exercise 1-3 days/week, some walking
fasting activity active # Moderate to intense exercise 3-5+ days/week
# Manage medical conditions for health-conscious recommendations
fasting condition add "high blood pressure"
fasting condition add diabetes
fasting condition remove diabetes
fasting condition list # Show current profile
fasting condition clear # Remove all conditions
# Get personalized meal recommendations based on your profile and current status
fasting recommend
# Get recommendations for specific food types
fasting recommend sandwiches
fasting recommend salads
fasting recommend "healthy breakfast"
# Advanced options for targeted recommendations
fasting recommend --type breakfast
fasting recommend --type lunch --calories 400
fasting recommend --type dinner --dietary vegetarian
fasting recommend pasta --calories 500 --dietary "gluten-free"
# Get exercise recommendations based on your activity level and conditions
fasting recommend --exercise
fasting recommend --exercise --type cardio --intensity moderate
fasting recommend --exercise --equipment "dumbbells, yoga mat"
# Get drink recommendations based on your profile
fasting recommend --drink
fasting recommend --drink --type smoothie --purpose "post-workout"
# Calories burned are automatically estimated using AI and your weight
# Supports flexible duration formats
fasting exercise "Running" 30 # 30 minutes
fasting exercise "Running" "30 minutes" # Same as above
fasting exercise "Cycling" "1.5 hours" # 1.5 hours (converted to 90 minutes)
fasting exercise "Weight lifting" "45min"
fasting exercise "Yoga" "1h"
# Override automatic estimation with manual calories
fasting exercise "Swimming" 30 --calories 400
# Weight logging with automatic unit conversion
fasting weight 200 # Uses your preferred unit (lbs or kg)
fasting weight 200lbs # Explicit imperial
fasting weight 90kg # Explicit metric
fasting weight 12oz # Also supports ounces
# Comprehensive dashboard with charts
fasting summary # All charts and current status
fasting summary --weight-chart # Show only weight chart
fasting summary --fast-chart # Show only fast duration chart
fasting summary --calorie-chart # Show only daily calorie chart
fasting summary --exercise-chart # Show only exercise calories burned chart
# Configure your preferred unit system
fasting setup --units # Interactive unit system setup
fasting setup --weight-unit # Configure just weight units (lbs/kg)
# Configure timezone for accurate "today's" data calculation
fasting setup --timezone # Interactive timezone setup
# Switch storage modes
fasting setup --local # Use local file storage
fasting setup --supabase # Use Supabase cloud storage
# Export all fasting data and configuration to a zip file
fasting export # Creates ~/fasting.zip with all data
# To restore on another machine:
# 1. Copy fasting.zip to the target machine
# 2. Extract: unzip ~/fasting.zip -d ~
# 3. Data will be restored to ~/.config/fasting/
# Override automatic estimation with manual calories
fasting meal "Chicken Salad" -c 450
fasting drink "Black Coffee" -c 5
# Combine size specification with manual override
fasting drink "Smoothie" --size "16oz" --calories 350
fast <start|end> - Start or end a fast with optional custom timingmeal <description> - Log a meal with automatic calorie estimation and personalized promptsdrink <description> - Log a drink with automatic calorie estimation and personalized promptsexercise <description> <duration> - Log exercise with flexible duration formats and personalized calorie burn estimationweight <value> - Log weight with automatic unit conversion (supports lbs, kg, oz, g)recommend [preference] - Get AI-powered personalized meal, exercise, and drink recommendationssummary - Show comprehensive dashboard with current status, charts, and historyactivity <level> - Set activity level (sedentary, moderate, active) for personalized recommendationscondition <action> [condition] - Manage medical conditions (add, remove, list, clear)setup - Configure OpenAI API key, unit system, timezone, and user profile preferencessetup --units - Configure unit system preference (imperial/metric)setup --weight-unit - Configure weight unit preference (lbs/kg)setup --timezone - Configure timezone preference for accurate date calculationssetup --supabase - Configure Supabase cloud storagesetup --local - Switch to local file storageexport - Export all fasting data and configuration to ~/fasting.zipclean - Delete all stored data (meals, weight, fasts, exercises)Fast Command:
-t, --time <time> - Specify start/end time
Meal/Drink Commands:
-c, --calories <number> - Override automatic calorie estimation with manual value-s, --size <size> - Specify portion size for more accurate calorie estimation (supports both imperial and metric)
Exercise Command:
-c, --calories <number> - Override automatic calorie burn estimation with manual value<duration> - Duration with flexible formats (required)
Recommend Command:
--meal - Get meal recommendations (default)--drink - Get drink/beverage recommendations--exercise - Get exercise/workout recommendations-t, --type <type> - Meal type (breakfast, lunch, dinner, snack) or drink type (smoothie, tea, coffee, etc.) or exercise type (cardio, strength, yoga, etc.)-c, --calories <number> - Target calories for the meal/drink or duration in minutes for exercise-d, --dietary <restrictions> - Dietary restrictions (vegetarian, vegan, gluten-free, etc.)--intensity <level> - Exercise intensity (low, moderate, high) - for exercise recommendations--equipment <items> - Available equipment (e.g., "dumbbells, yoga mat") - for exercise recommendations--location <place> - Exercise location (home, gym, outdoor) - for exercise recommendations--purpose <goal> - Drink purpose (hydration, energy, post-workout, relaxation) - for drink recommendations[preference] - Food/exercise/drink preference or category (optional)
Activity Command:
<level> - Activity level: sedentary, moderate, or activeCondition Command:
add <condition> - Add a medical condition (e.g., "high blood pressure", "diabetes")remove <condition> - Remove a medical conditionlist - Show current user profile (activity level and medical conditions)clear - Remove all medical conditionsWeight Command:
Summary Command:
--weight-chart - Show only weight trend chart--fast-chart - Show only fast duration chart--calorie-chart - Show only daily calorie intake chart--exercise-chart - Show only daily exercise calories burned chartSetup Command:
--units - Configure unit system preference (imperial/metric)--weight-unit - Configure weight unit preference (lbs/kg)--timezone - Configure timezone preference for accurate date calculations--supabase - Configure Supabase cloud storage--local - Switch to local file storageClean Command:
--config - Also delete API key configurationfasting/
├── bin/
│ └── cli.js
├── lib/
│ ├── index.js
│ ├── fasting.js
│ ├── weight.js
│ ├── units.js # NEW: Unit parsing and conversion
│ ├── calorie-estimator.js
│ ├── meal-recommender.js # NEW: AI-powered meal recommendations
│ ├── exercise-estimator.js
│ ├── charts.js
│ ├── storage.js
│ ├── supabase.js
│ ├── fast.js
│ ├── exercise.js
│ └── config.js
├── tests/ # Comprehensive test suite
│ ├── units.test.js # NEW: Unit system tests
│ ├── config-units.test.js # NEW: Unit configuration tests
│ ├── exercise-duration.test.js # NEW: Duration parsing tests
│ ├── meal-recommender.test.js # NEW: Recommendation tests
│ └── ...
├── .env.example
└── README.md
~/.config/fasting/
├── config.json # API key, settings, activity level, and medical conditions
├── meals.json # Meal and drink logs
├── weight.json # Weight history
├── fasts.json # Fast tracking history
└── exercises.json # Exercise logs
The app tracks your intermittent fasting periods:
Comprehensive imperial and metric unit support:
Accurate timezone handling for proper date calculations:
Comprehensive user profile management for personalized recommendations:
Automatic calorie estimation using OpenAI's GPT-4o model with personalized context:
--size for more accurate estimates-c flag if neededComprehensive recommendation system for meals, exercises, and drinks based on your profile:
Recommendation Features:
The app estimates calories burned using OpenAI's GPT-4o model with personalized context:
-c flag to specify exact calories burned if neededThe app supports optional cloud storage using Supabase for data synchronization across devices:
fasting setup --supabase to configure cloud storagefasting setup --localRequired Supabase Configuration:
Environment Variables (optional):
SUPABASE_URL=your_supabase_url
SUPABASE_SERVICE_ROLE_KEY=your_service_role_key
FASTING_STORAGE_MODE=supabase # or 'local'
Imperial System:
Metric System:
Duration Examples:
Weight Examples:
The app stores all data in ~/.config/fasting/ for secure, persistent access:
fasting setup to configure or update your API keyfasting export to create a backup zip file at ~/fasting.zipunzip ~/fasting.zip -d ~ to restore dataOPENAI_API_KEY as an alternative (takes precedence)fasting clean to delete meals/weight datafasting clean --config to delete everything including API key# Delete meals, weight, and fast data (keeps API key)
fasting clean
# Delete everything including API key configuration
fasting clean --config
If the OpenAI API is unavailable, the app falls back to default estimates (200 calories for meals, 50 for drinks).
This package can also be used as a Node.js module in your own applications:
import {
logMeal, logDrink, getTodaysEntries, getCalorieHistory,
logWeight, getWeightHistory,
startFast, endFast, getCurrentFast, getFastHistory, getFastStats,
logExercise, getTodaysExercises, getExerciseHistory
} from '@profullstack/fasting';
// NEW: Import recommendation and unit functions
import { generateMealRecommendations, formatRecommendations } from '@profullstack/fasting/lib/meal-recommender.js';
import { generateExerciseRecommendations, formatExerciseRecommendations } from '@profullstack/fasting/lib/exercise-recommender.js';
import { generateDrinkRecommendations, formatDrinkRecommendations } from '@profullstack/fasting/lib/drink-recommender.js';
import { parseSize, convertVolume, getSizeExamples } from '@profullstack/fasting/lib/units.js';
import { getUnitSystem, setUnitSystem, getActivityLevel, setActivityLevel, getMedicalConditions, addMedicalCondition, getUserProfile } from '@profullstack/fasting/lib/config.js';
// Fast tracking
startFast(); // Start fast now
startFast('2023-12-01 18:00'); // Start fast at specific time
const currentFast = getCurrentFast(); // Get active fast
const completedFast = endFast(); // End current fast
// Log meals and drinks programmatically
logMeal('Grilled chicken breast', 350);
logDrink('Orange juice', 120);
// Get today's entries
const todaysEntries = getTodaysEntries();
console.log(todaysEntries);
// Weight tracking
logWeight(175.5);
const weightHistory = getWeightHistory();
// Fast history and statistics
const fastHistory = getFastHistory(); // Completed fasts only
const fastStats = getFastStats(); // Statistics summary
// Calorie history
const calorieHistory = getCalorieHistory(); // Daily calorie totals
// Exercise tracking
logExercise('Running', 30, 300); // description, duration (min), calories burned
const todaysExercises = getTodaysExercises(); // Today's exercises
const exerciseHistory = getExerciseHistory(); // Daily exercise calorie totals
// NEW: User profile management
setActivityLevel('active'); // or 'sedentary', 'moderate'
const activityLevel = getActivityLevel();
addMedicalCondition('high blood pressure');
addMedicalCondition('diabetes');
const conditions = getMedicalConditions(); // ['high blood pressure', 'diabetes']
const profile = getUserProfile(); // Complete user profile
// NEW: AI-powered personalized recommendations
const mealRecommendations = await generateMealRecommendations('sandwiches', {
mealType: 'lunch',
calorieTarget: 400,
dietaryRestrictions: 'vegetarian'
});
const formattedMeals = formatRecommendations(mealRecommendations);
const exerciseRecommendations = await generateExerciseRecommendations('cardio', {
duration: 30,
intensity: 'moderate',
location: 'home'
});
const formattedExercises = formatExerciseRecommendations(exerciseRecommendations);
const drinkRecommendations = await generateDrinkRecommendations('smoothies', {
purpose: 'post-workout',
calorieTarget: 200
});
const formattedDrinks = formatDrinkRecommendations(drinkRecommendations);
// NEW: Unit system management
setUnitSystem('metric'); // or 'imperial'
const currentSystem = getUnitSystem();
// NEW: Unit parsing and conversion
const parsed = parseSize('500ml', 'volume');
const converted = convertVolume(16, 'fl oz', 'ml'); // 473.18
const examples = getSizeExamples('volume'); // ['250ml', '500ml', '1l', '1.5l']
Fast Tracking:
startFast(startTime?) - Start a new fast (optional custom start time)endFast(endTime?) - End current fast (optional custom end time)getCurrentFast() - Get active fast or nullgetFastHistory() - Get all completed fastsgetFastStats() - Get fast statistics (average, longest, etc.)Meal & Weight Tracking:
logMeal(description, calories) - Log a meal with description and calorie countlogDrink(description, calories) - Log a drink with description and calorie countgetTodaysEntries() - Get all meals and drinks logged todaygetCalorieHistory() - Get daily calorie totals grouped by datelogWeight(weight) - Log weight in poundsgetWeightHistory() - Get complete weight history with timestampsExercise Tracking:
logExercise(description, duration, caloriesBurned) - Log exercise with description, duration (minutes), and calories burnedgetTodaysExercises() - Get all exercises logged todaygetExerciseHistory() - Get daily exercise calorie totals grouped by dateNEW: AI-Powered Personalized Recommendations:
generateMealRecommendations(preference, options) - Generate personalized meal recommendationsformatRecommendations(recommendations) - Format meal recommendations for displaygenerateExerciseRecommendations(preference, options) - Generate personalized exercise recommendationsformatExerciseRecommendations(recommendations) - Format exercise recommendations for displaygenerateDrinkRecommendations(preference, options) - Generate personalized drink recommendationsformatDrinkRecommendations(recommendations) - Format drink recommendations for displayNEW: User Profile Management:
getActivityLevel() - Get current activity level ('sedentary', 'moderate', 'active')setActivityLevel(level) - Set activity level preferencegetMedicalConditions() - Get array of medical conditionsaddMedicalCondition(condition) - Add a medical conditionremoveMedicalCondition(condition) - Remove a medical conditionsetMedicalConditions(conditions) - Set medical conditions arraygetUserProfile() - Get complete user profile objectNEW: Unit System Management:
getUnitSystem() - Get current unit system ('imperial' or 'metric')setUnitSystem(system) - Set unit system preferenceparseSize(input, type) - Parse size input with unit detectionconvertVolume(value, fromUnit, toUnit) - Convert between volume unitsgetSizeExamples(type) - Get size examples for current unit systemNote: When using the module API, you need to provide calorie counts manually for basic functions. Automatic calorie estimation and AI recommendations via OpenAI are available through both CLI commands and the new recommendation API functions.
The project includes comprehensive unit tests for all functionality:
# Run all tests (core tests only, faster)
pnpm test
# Run all tests including AI tests (requires OpenAI API key, slower)
pnpm test:ai
# Run specific test suites
pnpm test:fast # Fast tracking tests
pnpm test:charts # Chart generation tests
pnpm test:fasting # Meal/drink logging tests
pnpm test:weight # Weight tracking tests
pnpm test:calorie-chart # Calorie chart tests
pnpm test:exercise # Exercise tracking tests
Core Tests (Fast, No API Required):
AI Tests (Slower, Requires OpenAI API Key):
Test Organization:
pnpm test (11 test files, ~66 tests)pnpm test:ai flag (14 test files, ~69 tests)Test Statistics:
All tests use isolated temporary directories to avoid interfering with real user data.
The project includes a git pre-commit hook that runs syntax checks before allowing commits:
# The hook runs automatically on git commit
git commit -m "Your commit message"
# To manually run the pre-commit check
pnpm run pre-commit
The pre-commit hook performs:
To bypass the pre-commit hook (not recommended):
git commit --no-verify -m "Your commit message"
The project includes example scripts demonstrating usage:
# Run CLI usage example
pnpm example
# Run API usage example
pnpm example:api
Example Files:
examples/basic-usage.js - Demonstrates CLI commands and workflowexamples/api-usage.js - Shows programmatic Node.js module usage# Patch version (bug fixes): 1.0.2 -> 1.0.3
pnpm version patch
# Minor version (new features): 1.0.2 -> 1.1.0
pnpm version minor
# Major version (breaking changes): 1.0.2 -> 2.0.0
pnpm version major
# Specific version
pnpm version 1.2.3
# Complete workflow
pnpm test # Run tests first
pnpm version patch # Bump version
pnpm publish --access public # Publish to npm
git push && git push --tags # Push to git
# Dry run to see what would be published
pnpm publish --dry-run
FAQs
A comprehensive CLI and Node.js module for 16:8 intermittent fasting with meal tracking, weight monitoring, and fast history with visual charts
We found that @profullstack/fasting demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 2 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Malicious Namastex.ai npm packages appear to replicate TeamPCP-style Canister Worm tradecraft, including exfiltration and self-propagation.
Product
Explore exportable charts for vulnerabilities, dependencies, and usage with Reports, Socket’s new extensible reporting framework.
Product
Socket for Jira lets teams turn alerts into Jira tickets with manual creation, automated ticketing rules, and two-way sync.