Using the CLI

If you've used claude (Anthropic's CLI) or gh (GitHub's), amy will feel familiar, but it's deliberately calmer. It never starts a side effect without telling you what it's about to do, and it never starts a side effect without your enter key.

Install

The CLI ships with the repo:

git clone https://github.com/yatendra2001/amy_health_assistant.git
cd amy_health_assistant
bun install
bun run amy

For one-shot use without an alias, bun run amy <command> works from the repo root. To make it feel like a real binary:

alias amy='bun /full/path/to/amy_health_assistant/src/cli.ts'

Add that to your ~/.zshrc / ~/.bashrc. From here on this page assumes amy is on your PATH.

Run it

Just type amy with no arguments:

amy

You'll get the guided experience, a deliberate walkthrough that introduces itself, signs you in, asks you to connect a wearable, backfills your history, optionally takes a lab report, surfaces a few questions worth asking, then drops you into chat.

I'm Amy   →   sign in   →   connect   →   history   →
bloodwork   →   a few things worth asking   →   ask

Every step prints what it's about to do, then waits for enter. If you don't want a step, escape, it skips cleanly. This is the calm-design philosophy: nothing happens until you decide.

Commands

Day to day

Your data

Account

Examples

# Sign in and connect a Whoop
amy login
amy connect whoop

# Pull a year of history once it's connected
amy import 365

# Upload a recent lab panel
amy upload-labs ~/Downloads/2026-05-panel.pdf

# Ask a one-shot question (skips chat)
amy ask "what's my average HRV over the last 90 days?"

# Drop into chat
amy

Inside chat

Once chat is open, just type. Press enter to send. The dropdown underneath your input shows live suggestions (after /suggest) or filters slash commands as you type /.

Slash commands

Slash commands are hidden until you type /. They're for things that aren't conversations, they manipulate state or surface metadata.

The slash menu is intentionally minimal. Everything else is a real question to Amy.

Suggestions

/suggest populates the dropdown with 3-7 ranked questions, each labeled with the agents that would answer it (DS, DE, HC) and a tier chip (solo / duo / trio). Arrow-key down to pick one, or keep typing to ignore them and ask your own thing. Picking a suggestion or submitting your own message hides them, re-run /suggest to refresh.

Trace

/trace dumps the last turn as JSON. Inside you'll find the routing decision, every agent's input + output, every validator gate verdict, the Critic's review, the final Fact Sheet, and the cumulative cost. This is what the SDK's Turn object would look like, the chat UI just hides it behind a slash command so the default experience stays calm.

How the CLI talks to the backend

The CLI is just an HTTP client. Every command is a thin wrapper around the same API your mobile app would call.

The CLI uses the TypeScript SDK shape under the hood. Anything you can do from the CLI, you can do from the SDK, from curl, or from any other client. The CLI has no special powers.

Backend selection, direct Anthropic vs API key vs OpenRouter, is the same as for the Worker. See the backends table in the README.

Verbose logging

AMY_DEBUG=1 amy ask "…"

AMY_DEBUG=1:

• Prints full stack traces on errors (instead of just the message).
• Surfaces extra per-step diagnostics in chat.

Everything the CLI does also lands in ~/.amy/logs/YYYY-MM-DD.jsonl as structured JSON, regardless of AMY_DEBUG. To pull every error from today:

grep '"level":"error"' ~/.amy/logs/$(date +%F).jsonl | jq .

For deeper debugging, what state the CLI sees + what it fetched last from the cloud, run:

amy debug              # human-readable
amy debug --json       # machine-readable
amy debug --user=u_…   # fetch remote turn traces for a user
amy debug --request=req_…   # fetch a specific request's trace

Environment variables

Where to next

• Local development, modifying the CLI itself.
• SDK: TypeScript, the same surface, programmatic.
• Getting started, using the API directly without the CLI.
• Architecture, what's happening underneath each command.