Open Wonder CLI (Draft)

Agent-oriented CLI for Open Wonder (@openwonder/ow), built with oclif.

Quick start

Interactive sign-in (humans / superadmins)

npm install -g @openwonder/ow
ow login --env local         # http://localhost:3000
ow login --env dev           # https://dev.openwonder.com
ow login --env prod          # https://app.openwonder.com
ow status --json
ow config:list
ow doctor

Tunnel override for local dev:

ow login --env local --base-url https://dev-app-yourslug.openwonder.com

API token (Slack, CI, automation)

ow auth:token:import --token <org-api-token> --env prod
# or
export OPEN_WONDER_API_TOKEN=<token>
ow status --json

Superadmins can mint tokens (including internal scopes such as gtm:read) after ow login:

ow login --env prod
ow tokens:create --name "GTM Slack Agent" --scope gtm:read --org <org-id> --json

Legacy ~/.openwonder/cli.json users:

ow auth:migrate

Profiles and environments

Each --env maps to a named profile (local, dev, prod) in ~/.openwonder/config.json. Secrets are stored in the OS keychain when available, otherwise ~/.openwonder/credentials.json (mode 0600).

ow config:use dev
ow context:set --brand-id <uuid>

Credential precedence:

1. OPEN_WONDER_API_TOKEN (API token)
2. OPEN_WONDER_USER_TOKEN (user JWT)
3. Active profile keychain/file entry

Command contract (agent-oriented)

• Human (default in a TTY): short, colored lines for auth commands (login, logout, status, doctor).
• --json: compact JSON on stdout for scripts and agents.
• API commands (brands:list, generate:image, …): stdout JSON by default; use --json for single-line output.
• Errors: stderr JSON { code, message, details? }.
• Exit codes: 0 success, 2 validation, 3 auth, 4 not found, 5 rate-limited, 1 other.

oclif topic syntax

Topic commands use colons, not spaces:

| Spaced (human-friendly) | oclif command | |-------------------------|---------------| | auth status | auth:status | | config list | config:list | | context get | context:get | | auth token import | auth:token:import |

Top-level aliases exist for common flows: ow login, ow logout, ow status.

When using pnpm run cli from the repo root, the wrapper accepts either form — it normalizes auth status → auth:status automatically. The global ow binary requires colon syntax for topic commands.

Auth commands

| Command | Description | |---------|-------------| | ow login --env local\|dev\|prod | Browser PKCE login → user JWT | | ow logout [--profile] | Remove stored credentials | | ow status [--json] | Profile + /api/cli/whoami | | ow auth:token:import --token <t> | Store org API token | | ow auth:migrate | Migrate legacy cli.json | | ow auth:token:set | Deprecated → use token import |

Config commands

| Command | Description | |---------|-------------| | ow config:use <profile> | Switch active profile | | ow config:list [--json] | List profiles | | ow doctor | Auth + API health check |

API commands

• ow context:set / ow context:get
• ow brands:list, ow brand:info
• ow visual-styles:list
• ow assets:list, ow assets:get
• ow jobs:status [--wait]
• ow permissions:get, ow usage:get
• ow gtm:stats:get [--since] [--until] [--period]
• ow gtm:organizations:list [--phase trial] [--q] [--activity] [--trial-ending-within] [--min-generations-mtd] [--since] [--until] [--period] [--min-generations-in-range] [--sort] [--order] [--limit] [--offset]
• ow gtm:organizations:get --slug <slug>|--id <cuid> [--since] [--until] [--period]
• ow gtm:onboarding:list [--since] [--no-active] [--limit] [--offset] (internal sales/ops; requires gtm:read)
• ow gtm:onboarding:get --brand-id <cuid> (internal sales/ops; requires gtm:read)
• ow tokens:create --name <name> --scope <scope> [--org <id>]
• ow generate:image --style-id <id> --prompt "..." [--wait]
• ow version:check [--fail-if-outdated]

Brand resolution: --brand-id → OPEN_WONDER_BRAND_ID → profile brand_id.

Local development

From repository root:

pnpm run cli:install
pnpm run openapi:generate
pnpm run cli:generate
pnpm run cli:lint
pnpm run cli:build

Apply the CLI login migration before testing browser login locally:

npx prisma migrate dev

Run from repository root (after pnpm run cli:build):

pnpm run cli -- login --env local
pnpm run cli -- status --json
pnpm run cli -- --help

Or from packages/cli:

cd packages/cli
node dist/bin/run.js login --env local

OpenAPI sync

pnpm --filter @openwonder/ow run client:generate

Public distribution (npmjs)

npm install -g @openwonder/ow
npx -y @openwonder/ow@latest --help

Publish via GitHub Actions workflow CLI Publish after bumping packages/cli/package.json and CHANGELOG.md.