Use the freddy CLI

The freddy CLI is a small command-line tool that signs you in, connects your wearables, and queries your health data without the copy-pasted URLs or the shell recipe the older agent guides describe. It is the easiest way to use freddy from a terminal, and it is built for headless AI agents (Claude Code, Cowork, your own bot) that can shell out to a command.

It is free to install and open under the MIT license. The CLI wraps the device-flow sign-in, token storage and refresh, the wearable connect handoff, and the MCP calls, so you never touch any of that plumbing yourself.

Install

You can run it on demand with npx, or install it globally:

npx @freddy-coach/cli login        # run any command on demand
# or
npm i -g @freddy-coach/cli         # then just: freddy <command>

It needs Node.js 20 or newer. The examples below assume the global install (freddy ...); if you prefer npx, prefix each command with npx @freddy-coach/cli.

Sign in

freddy login

This prints a sign-in URL. Open it in any browser, approve, and the CLI stores your tokens. By default login requests the mcp account:read scopes, which are enough to read your profile and query your data.

To also connect, sync, or disconnect wearables, request the broader scope up front:

freddy login --scope "mcp account:read connections:write"

You can check your status at any time:

freddy status

It shows whether you are signed in, which host you are signed in to, your scopes, and whether your access token is still valid. Access tokens last one hour and refresh automatically on the next command, so you rarely need to think about them.

Connect a wearable

List what you can connect:

freddy providers

Then connect one. This needs the connections:write scope (see Sign in above):

freddy connect oura

The CLI prints a URL. Open it in your browser, authorize freddy on the wearable's site, and the CLI waits until the connection lands, then confirms it. From that point freddy syncs that wearable daily.

A few notes:

• Replace oura with any connectable provider, for example polar, withings, suunto, or intervals-icu. Run freddy providers to list them all; a few are in limited beta, and your freddy dashboard shows what you can connect today.
• If you signed in without connections:write, connect will tell you to run freddy login --scope "mcp account:read connections:write" first. Re-running login with the broader scope is safe; it does not lose your existing connections.
• A few providers connect with an API key rather than a browser flow (Hevy, for example). freddy connect does not handle those; connect them from your freddy dashboard instead.

Query your data

Once a wearable is connected and synced, ask for metrics by name over a recent window:

freddy query --metrics hrv,sleep_duration --days 7

--metrics is a comma-separated list. --days is a number from 1 to 365. For longer ranges, use --start and --end with YYYY-MM-DD dates. Add --include-raw to get the full provider payloads alongside the summary.

To discover what is available to query:

freddy metrics          # the metrics you can ask for, with date ranges and units
freddy profile          # your account, plan, and connected wearables

Manage connections

freddy sync oura            # trigger an incremental sync now
freddy disconnect oura      # disconnect and remove that wearable's synced data
freddy logout               # revoke this device and clear local tokens

disconnect is destructive: it removes the data freddy synced for that wearable. logout revokes the CLI's access on the server and deletes the local tokens, so the next command will ask you to sign in again.

Machine-readable output (for agents)

Every command accepts --json, which prints a single JSON object to stdout instead of human-readable text. This is what you want when an agent or a script drives the CLI:

freddy profile --json
freddy query --metrics hrv --days 30 --json
freddy status --json

If you are building an agent integration, the agent quickstart covers the CLI and the underlying REST and MCP surface.

Configuration

Two environment variables change where the CLI talks and where it stores tokens:

Tokens live in credentials.json inside the config directory, written with 0600 permissions (readable only by you). Keep that file private; anyone who can read it can act as you until you freddy logout or rotate.

Scopes

login requests scopes; each command needs certain ones:

The default mcp account:read covers reading and querying. Add connections:write when you want to manage wearables.

Troubleshooting

"Session expired. Run freddy login again." Your refresh token is no longer valid (it expires after 60 days, or was revoked). Run freddy login to sign in fresh.

"Missing connections:write" or a scope error on connect/sync/disconnect. You signed in with read-only scopes. Run freddy login --scope "mcp account:read connections:write", then retry.

connect <provider> says the provider uses an API key. A few providers (Hevy, for example) connect with an API key rather than a browser flow. Connect them from the freddy dashboard.

"Timed out waiting for the connection." The browser step has a ten-minute window. If you finished it after that, just run freddy connect <provider> again; it will detect the existing connection.

Unknown provider. Run freddy providers to see the exact slugs you can use.

For more agent-specific errors (audience mismatch, revoking an agent's access), see Troubleshooting agent sign-in.

Need help?

Email support@freddy.coach, or message us in-app at freddy.coach/app/chat.