How to give an AI agent access to your health data from the command line
Headless AI agents (Claude Code, Cursor, Cowork, your own bot) are good at multi-step work: pull some data, reason over it, take an action, check the result. Your wearable data is a natural thing to point one at. "Look at my last 30 days of sleep, find the worst nights, and tell me what they had in common" is exactly the kind of question an agent answers well.
The friction was always the wiring. Giving an agent read access to your Oura or WHOOP or Polar data meant registering an OAuth client, walking a device-authorization flow, storing and refreshing tokens, and speaking the Model Context Protocol to actually fetch metrics. That is a real afternoon of work, and most of it is plumbing nobody wants to own.
A command-line tool removes that afternoon. This piece walks through what it looks like to give an agent your health data in a couple of commands, what is happening underneath, and when you would still want to do it the long way instead.
What "headless agent" means here
A headless agent is one that runs without a chat UI you click around in: a coding agent in your terminal, a scheduled job, a script you wrote, a bot in a server somewhere. It can run shell commands but it cannot paste a URL into a "Connectors" settings field the way you would in a desktop chat app. That distinction matters, and it is why a CLI fits this case better than the paste-a-URL setup that consumer apps use.
If you are using a desktop chat app instead (Claude, ChatGPT, Perplexity), you do not need any of this. You connect your wearable once on a dashboard, copy a personal URL, and paste it into the app. The command-line path below is for the headless case.
The short version
freddy is a hosted multi-wearable server that reads from your wearables' APIs and exposes them over MCP. Its CLI, published as @freddy-coach/cli, wraps the whole flow. From a terminal:
npx @freddy-coach/cli login --scope "mcp account:read connections:write"
npx @freddy-coach/cli connect oura
npx @freddy-coach/cli query --metrics hrv,sleep_duration --days 7The first command prints a sign-in URL; you open it in a browser, approve, and the CLI stores your tokens. The second prints a URL to authorize your wearable. The third reads your data. Swap oura for whoop, polar, withings, strava, and others. The CLI is free and open source under the MIT license.
An agent runs the same commands. Because every command takes a --json flag that prints a single machine-readable object, the agent gets structured output it can reason over directly:
freddy query --metrics hrv,sleep_duration,resting_heart_rate --days 30 --jsonThe agent never sees a raw token or touches an OAuth redirect. It just runs commands.
What is actually happening underneath
Nothing magic, just the standard pieces wired together for you:
Device-flow sign-in. The CLI uses the OAuth 2.0 Device Authorization Grant (RFC 8628), the same flow a smart TV or a developer CLI uses when there is no reliable browser callback. It registers a client, requests a code, shows you a URL, and polls until you approve. No redirect_uri to configure, which is exactly why it suits headless tools.
Token storage and refresh. Your access token (good for about an hour) and a longer-lived refresh token are written to a file in your home directory, readable only by you. The CLI refreshes the access token automatically on the next command, so the agent never has to think about expiry.
MCP for the data. Queries go through the Model Context Protocol, the open standard AI clients use to pull data from external sources. The CLI calls the same query_metrics and list_metrics tools an MCP-speaking chat app would, and hands you the result. Run the metrics command to see exactly which metrics your connected wearables expose, with their date ranges and units, before you query.
Scopes, and what the agent cannot do
Access is scoped. The default sign-in requests read access (mcp account:read), which is enough to query your data and read your profile. Connecting or disconnecting wearables needs a broader scope (connections:write) that you request explicitly at sign-in. This means you can hand an agent a read-only session and know it cannot change your connections.
Some things are deliberately out of reach of any token. Deleting your account, for instance, is not reachable from the command line or from an agent at all; it requires you, signed in to the dashboard. The boundary is intentional: an agent should be able to read your data and manage wearables if you let it, but not perform the one irreversible action.
You can review and revoke any agent's access from your dashboard at any time, which immediately invalidates its tokens.
When you would still do it the long way
A hosted CLI is the fast path, not the only one. Two honest alternatives:
Wire the flow yourself. If you are building a product and want to embed the sign-in rather than shell out to a tool, the device flow, the REST surface, and the MCP tools are all documented. You do the same work the CLI does, with full control over the UX. This is the right call if the integration is part of something you ship.
Self-host the server. If you would rather not have a third party hold a copy of your data, Open Wearables is a community project that runs the wearable-to-MCP bridge on hardware you control. You handle the OAuth setup and keep the server running. This is the right call if you self-host other things and want your health data to stay on your own machine. A hosted service like freddy holds your synced data on its servers under the terms of its privacy policy; self-hosting keeps it local. Pick based on which tradeoff you prefer.
For most people who just want their agent to read their wearable data today, the CLI is the least-effort path that works.
Cost
The CLI itself is free to install and free to use. freddy is free for a single wearable and $19/year for unlimited connections and full history on the paid tier. The AI agent on the other end has its own pricing, separate from any of this.
Where to start
If you already have a wearable, install the CLI, run login with the connection scope, connect your device, and query. Five minutes, no integration code. From there, point your agent at the same commands and let it pull what it needs.
If you are choosing a wearable with good developer support, the comparison of wearable APIs for AI agents covers which devices expose the richest data. And if you want the broader picture of how wearables, AI clients, and MCP servers fit together, start with connecting wearable data to AI.
Updated 2026-06-01. Pricing and feature details verified 2026-06-01. Check vendor sites for current details before committing.