Use the Healthcode CLI

The health CLI is the terminal interface to Loops. It scaffolds agent workspaces, validates them as deployable health apps, and calls Healthcode — Ollie’s agent-authoring model — to turn natural-language prompts into concrete health commands.

This guide walks you through installing the CLI, authenticating against a Loops organization, and running your first Healthcode session.

1. Install

curl -fsSL https://raw.githubusercontent.com/Ollie-Health/Health-CLI/main/scripts/install.sh | sh
health --help

The installer downloads the latest release for your platform, verifies the SHA-256 checksum, and installs health to ~/.local/bin. Apple Silicon macOS and Linux x86_64 are released today.

To verify the installation:

health doctor

You should see offline connected and the other providers reporting missing_credentials until you authenticate.

2. Authenticate

The device-link login flow (health login --browser --company <slug>) requires a follow-up backend release. Until then, use manual token auth:

health login \
  --token "$OLLIE_LOOPS_TOKEN" \
  --company "$OLLIE_COMPANY_SLUG" \
  --email you@example.com \
  --api-url https://loops.ollie.health

The token is stored in ~/.ollie/health/auth.toml with permissions 0600. The CLI sends it only as an Authorization: Bearer header; the raw token never appears in a request body.

To get a token, ask your Loops admin to create one in the Loops web app — Settings → API tokens. The token must be scoped to allow cli:run (or, during the v0 transition, must match WORKER_SYSTEM_API_KEY). See API tokens for the full scope model.

3. Scaffold an agent

health init care-nav --channel whatsapp
cd care-nav

This generates a complete workspace: agent.yaml, app.yaml, company.yaml, routing.yaml, channel-specific tool calls under toolcalls/, sample loops under loops/, a Cloudflare Worker adapter scaffold, and a README.md. None of these contain secrets.

4. Run a Healthcode session

Try a one-shot:

health code --hosted --prompt "scaffold a care navigation whatsapp agent that calls FACIAL_SCAN then routes BP through HEALTH_CALCULATOR"

You’ll see:

Healthcode session
session_id: ...
turn_id: ...
intent: build_agent
provider: ollie-hosted
model: healthcode-v0
target: local_terminal
available_now: true
data_boundary: developer_infrastructure_only

assistant:
I'll scaffold the WhatsApp workspace, save a route plan that names both
connectors, and verify before sync.

tool_plan:
- [scaffold] health init care-nav --channel whatsapp -- scaffold workspace
- [route]    health route --task agent --prompt "..." --save --name care-nav
- [tools]    health tools list -- confirm bindable connectors
- [build]    health agent build -- validate manifest
- [verify]   health verify -- preflight before sync

audit_event: cli.code.turn.hosted/cli-code-<uuid>

Or launch the REPL:

health code

Ctrl+H toggles between offline and hosted modes. Esc exits.

5. Use a built-in tool from your loop

Once your workspace is scaffolded, you can call built-in tools from your loop code. Edit loops/sample.ts:

export class HealthLoop extends Workflow {
  async run(event: HealthEvent<{ systolic: number; diastolic: number }>, step: HealthStep) {
    const classification = await step.do("classify-bp", async ({ ctx }) =>
      ctx.HEALTH_CALCULATOR.bloodPressure({
        systolic: event.body.systolic,
        diastolic: event.body.diastolic,
      }),
    );
 
    return {
      category: classification.category,
      urgency: classification.urgency,
    };
  }
}

Then validate:

health agent build
health verify

health verify is the final preflight. It fails until route plans, data source cards, training plans, sandbox plans, hosted contracts, loop auth binding, app identities, and secret-free artifacts are all present.

6. What’s next

• Healthcode — the model behind health code: wire contract, safety gates, roadmap.
• Tools — every built-in tool you can call from a loop (FACIAL_SCAN, HEALTH_CALCULATOR).
• Build your first loop — same workflow, end-to-end, from the web app side.
• API tokens — token scopes, revocation, rotation.

Troubleshooting