Floe CLI

The full Floe platform from your terminal — setup, metered calls, agents, keys, budgets, policies, billing, funds, and phone. Built for humans and for AI coding agents.

npx @floelabs/cli init

floe init authenticates with your developer key, creates (or selects) an agent, mints its runtime key into your OS keychain, and ends with the only thing that matters — the base-URL swap for your existing OpenAI-compatible client, key already filled in:

from openai import OpenAI
client = OpenAI(base_url="https://credit-api.floelabs.xyz/v1", api_key="floe_…")

Every response carries X-Floe-Cost-USDC. One key meters chat, embeddings, speech and transcription across 15+ vendors — one bill, in USDC.

Quickstart

npm install -g @floelabs/cli
floe init                   # authenticate, set up an agent + key
floe status                 # am I set up? balance, budgets, active agent
floe chat "hello"           # one metered call, cost printed
floe test --voice           # STT → LLM → TTS: three legs, one key, one bill

Commands

floe help <command> prints each command's full usage and flags.

Get started

| Command | What it does | |---|---| | floe init | Authenticate, set up an agent + key, print the base-URL swap | | floe status | Am I set up? Balance, budgets, active agent and key | | floe use | Switch this machine to another agent (keys kept per agent) | | floe test | Make one real metered call and print its cost |

Metered calls

| Command | What it does | |---|---| | floe chat | Send a prompt through the metered gateway | | floe embed | Create embeddings through the metered gateway | | floe speak | Text-to-speech through the metered gateway (writes a file) | | floe transcribe | Transcribe an audio file through the metered gateway | | floe pay | Call any x402 vendor through the metered proxy |

Agents & limits

| Command | What it does | |---|---| | floe agents | list | get | create | pause | resume | close | lock — agent fleet | | floe keys | list | create | revoke | rotate — agent runtime keys | | floe devkeys | list | create | revoke | rotate — developer (floe_live_) keys | | floe budget | show | set | clear | reserve — cap agent spend | | floe policy | list | create | update | revoke | reset | chain | test — spend policies | | floe allowlist | show | set | add | remove — merchant allowlist | | floe credit | bounds | open — credit-line inspection and opt-in open |

Observability & billing

| Command | What it does | |---|---| | floe activity | Unified spend/activity feed with filters | | floe usage | Spend series | summary | coverage — usage analytics | | floe ledger | Cross-source spend ledger, grouped | | floe billing | mtd | invoice | export | charges — billing and exports | | floe account | show | rename — account identity | | floe team | members | invite | revoke-invite | set-role | remove — team roster |

Money

| Command | What it does | |---|---| | floe funds | withdraw | move | list | address | topup | sessions — move money | | floe cashout | start | list | status | cancel — cash out USDC to fiat |

Platform

| Command | What it does | |---|---| | floe webhooks | list | create | get | pause | enable | delete | test | rotate-secret | deliveries | | floe models | Model catalog with modalities and pricing | | floe estimate | Estimate a call cost without spending | | floe providers | list | set | enable | disable | remove — BYOK provider keys | | floe phone | search | buy | list | release | calls | usage | voice | test-call — Floe Phone | | floe actions | list | report — cost-per-action rollups and outcomes | | floe orchestrators | connect | list | rotate | enable | disable | remove — Vapi/Retell/Bland | | floe vendors | status — live-verified vendor probes |

Two keys, handled for you

Floe has a developer key (floe_live_…, from the dashboard) for managing agents, and per-agent runtime keys (floe_…) that the gateway meters. The CLI stores both in your OS keychain and always sends the right one — you never pick. On systems without a usable keychain (headless Linux, some containers) it falls back to ~/.config/floe/credentials.json with 0600 permissions and tells you so.

Runtime keys are stored per agent, so floe use <agent> switches this machine between agents without re-minting keys — the first switch to an agent mints its key once (agents cap at 5 keys), and every switch after that reuses it.

Conventions

• --json on every command — machine-readable output for CI and coding agents.
• --yes skips confirmation on destructive or money-moving commands (agents close, keys revoke, funds withdraw, …). Non-interactive runs require it — a script never destroys something by default.
• Exit codes: 0 ok · 1 error · 2 usage · 4 auth · 5 payment/budget.
• --api-url <url> overrides the API base on any command.

Environment

Headless / CI: set FLOE_API_KEY (developer key) and/or FLOE_AGENT_KEY (runtime key); env vars always win over the keychain. FLOE_API_URL overrides the API base.

For AI agents

The CLI is a first-class surface for coding agents:

• Every command takes --json and emits stable, machine-readable JSON — parse it instead of scraping human output. (Metered commands wrap the API body with model/cost fields, and filtered lists are reconstructed, so it's a stable CLI schema, not always the raw API body.)
• Nothing hangs on a prompt: non-interactive destructive calls fail fast with exit 2 unless --yes is passed.
• Bootstrap without a keychain: export FLOE_API_KEY (and FLOE_AGENT_KEY for metered calls) and every command works immediately — no init, no stored state.
• Exit codes are stable and meaningful — branch on 4 (re-auth) and 5 (out of budget).

Development

pnpm install
pnpm build        # tsup → dist/
pnpm typecheck
pnpm test
node dist/bin.js --help

Merging to main publishes to npm automatically when package.json has a new version.

License

MIT © Floe Labs