fitbit-health_skill

Overview

This skill provides a command-line interface to query Fitbit health data including activity, sleep, heart rate, and weight. It helps retrieve daily summaries, specific metrics (like steps or heart rate), and profile information after a one-time OAuth setup. Use it to integrate Fitbit data into workflows, scripts, or quick lookups without opening the Fitbit app.

How this skill works

After registering a personal app on Fitbit and running the interactive configure/login flow, the CLI stores OAuth tokens locally and refreshes them automatically. Commands request data from Fitbit's Web API and return plain text or JSON. Common commands include profile, activity, summary, and today, with options for timezone override, verbosity, and JSON output.

When to use it

• You need quick access to your Fitbit steps, sleep, heart rate, or weight from the terminal.
• Building scripts or cron jobs that pull daily summaries or metrics for logging or reporting.
• Answering user questions that require up-to-date Fitbit data during conversations.
• Debugging or auditing Fitbit authentication and token status.
• Extracting JSON data for integration with other tools or dashboards.

Best practices

• Register a personal Fitbit app and set the callback to http://localhost:18787/callback before running configure.
• Run fitbit login in a secure environment and keep tokens file (~/.config/fitbit-cli/tokens.json) permissioned (chmod 600).
• Use --json for structured output when piping results into scripts or analytics tools.
• Pass explicit dates in YYYY-MM-DD format to ensure reproducible queries; default is today.
• Use --tz to override timezone when querying data for a different locale.

Example use cases

• Get today's step count: fitbit activity steps
• Retrieve yesterday's full daily summary as JSON for ingestion: fitbit summary 2026-01-25 --json
• Check authentication status and token validity: fitbit status
• Automate nightly exports of sleep and heart rate for long-term trend analysis in a cron job
• Quickly view profile information or weight history from the terminal