# CLI

Install: `npm install -g @ozma_app/cli` or run via npx.

```bash
npx @ozma_app/cli --help
```

Install hub: [https://ozma.app/connect](https://ozma.app/connect)

**Package:** `@ozma_app/cli` — in-repo v0.2.0+; published versions may lag.

## Config

Path: **`~/.ozma/config.json`**

| Field | Purpose |
|-------|---------|
| `apiKey` | `ozma_live_…` — required for `ozma call` |
| `sessionToken` | `sess_…` — control plane; preferred when both set |
| `apiUrl` | Default `https://api.ozma.app` |
| `gatewayUrl` | Default `https://gateway.ozma.app` |

Env overrides: `OZMA_API_URL`, `OZMA_GATEWAY_URL`.

All commands support **`--json`**. API failures exit code **1** with `{ ok: false }`.

## Auth

| Command | Description |
|---------|-------------|
| `ozma login [--key] [--email] [--code]` | Browser, paste key, or OTP login |
| `ozma logout [--all]` | End session; `--all` clears API key too |
| `ozma signup --email [--name]` | Human signup — **Turnstile required in prod; CLI rejected** — use web or `login --email` |
| `ozma verify --token` | Email verification token exchange |
| `ozma register` | Auto-register key (**0 credits**) |
| `ozma whoami` | `GET /v1/me` |

## Profile & providers

| Command | Description |
|---------|-------------|
| `ozma profile show\|update […]` | Own org profile |
| `ozma providers [slug] [--q]` | Public provider directory |

## Catalog & market

| Command | Description |
|---------|-------------|
| `ozma categories` | Category list |
| `ozma search <query> [--category] [--sort]` | Search |
| `ozma inspect <slug> [--schema\|--stats\|--history\|--ranks\|--endpoints\|--openapi]` | API detail views |
| `ozma leaderboard <board> [--category]` | Merit boards |
| `ozma market overview\|activity [--limit]` | Market summary / activity feed |
| `ozma request-api --query [--email] [--notes]` | Request missing API |

Boards: `top_grossing`, `most_used`, `most_reliable`, `best_value`, `trending`, `new_rising`.

## Consumer — keys, call, usage

| Command | Description |
|---------|-------------|
| `ozma provision [slug]` | Register if no key |
| `ozma call <slug> <endpoint> …` | Gateway proxy (API key only) |
| `ozma terms show\|status\|accept <slug>` | Provider terms (`accept` needs session) |
| `ozma usage [--from] [--to]` | Usage history |
| `ozma keys list\|create\|revoke\|patch` | Key management |
| `ozma budget set [--key] [--budget] [--per-call-max] [--daily-cap] [--approval-mode]` | Spend caps |
| `ozma balance` | Credit balance |

Key create/patch flags: `--name`, `--scopes`, `--budget`, `--per-call-max`, `--daily-cap`, `--approval-mode`.

## Billing

| Command | Maps to |
|---------|---------|
| `ozma billing status` | `GET /v1/billing/balance` |
| `ozma billing packs` | `GET /v1/billing/packs` |
| `ozma billing setup` | SetupIntent — human confirms card |
| `ozma billing portal` | Billing Portal URL |
| `ozma billing checkout [--pack\|--amount]` | Stripe Checkout |
| `ozma billing auto-reload --enable\|--disable [--threshold] [--amount]` | Auto-reload |

## Provider

| Command | Maps to |
|---------|---------|
| `ozma provider list\|get <id>` | List/detail |
| `ozma provider create <source> [--rapidapi]` | Import OpenAPI |
| `ozma provider patch <id> [--name] [--summary] …` | Metadata |
| `ozma provider credentials <id> --secret [--injection] [--injection-name]` | Upstream secret |
| `ozma provider pricing <id> [--file\|--endpoint-id --price-cents]` | Pricing |
| `ozma provider pricing-cancel <apiId> <endpointId>` | Cancel pending increase |
| `ozma provider verify <id>` | Smoke test |
| `ozma provider publish <id> [--skip-verify] --accept-terms` | Go live |
| `ozma provider unpublish <id>` | Live → draft |
| `ozma provider connect` | Stripe Connect onboard |
| `ozma provider analytics` | Provider stats |
| `ozma provider documents list\|create\|activate` | Legal documents |

Alias: `ozma publish <source>` = `ozma provider create`.

### Documents examples

```bash
ozma provider documents create \
  --kind terms --source hosted --version 1.0.0 \
  --markdown ./terms.md --api-id api_123 \
  --acceptance-mode required

ozma provider documents activate doc_123
```

## Connect (MCP installer)

```bash
ozma connect                      # all detected agents
ozma connect --pick               # interactive multi-select
ozma connect --all                # every supported client
ozma connect --client cursor      # single client
ozma connect --project --rules    # repo-scoped rules
ozma connect --dry-run --json
ozma connect --key ozma_live_…    # embed key (plaintext warning)
ozma connect --no-key             # keyless dev config
```

Clients: `cursor`, `claude-code`, `codex`, `vscode`, `windsurf`, `cline`, `gemini`, `zed`, `claude-desktop`.

## Turnstile signup limitation

`ozma signup` cannot pass Cloudflare Turnstile in production. Use [https://ozma.app/signup](https://ozma.app/signup) or `ozma login --email`.

## Examples

```bash
ozma login --email you@example.com --code 123456
ozma search "weather" --json
ozma call frankfurter /latest --query from=USD --query to=EUR --json
ozma keys create --name agent-1 --budget 500
ozma budget set --budget 500 --daily-cap 100 --per-call-max 50
ozma provider credentials api_123 --secret sk_x --injection bearer
ozma provider pricing api_123 --endpoint-id ep_456 --price-cents 5
ozma provider publish api_123 --accept-terms
ozma terms accept my-api-slug --yes
```