Open Wonder CLI (Draft)

This package contains the first in-repo draft of the Open Wonder CLI using oclif.

Command Contract (Agent-Oriented)

• Use --json for machine-readable output.
• Success responses are emitted to stdout as JSON.
• Error payloads are emitted to stderr as JSON.
• Exit codes:
  • 0 success
  • 2 validation errors
  • 3 auth errors
  • 4 not found
  • 5 rate-limited
  • 1 other API/internal errors

Context Model

The CLI supports brand-scoped abstraction on top of API endpoints.

Brand resolution order for brand-scoped commands:

1. --brand-id
2. OPEN_WONDER_BRAND_ID
3. saved context via ow context:set --brand-id ...

Commands (Draft)

• ow auth:token:set --token <token> [--base-url <url>] [--json]
• ow context:set [--brand-id <id>] [--base-url <url>] [--json]
• ow context:get [--json]
• ow brands:list [--base-url <url>] [--json]
• ow brand:info [--brand-id <id>] [--base-url <url>] [--json]
• ow visual-styles:list [--brand-id <id>] [--type USER|DEMO] [--json]
• ow assets:list [--brand-id <id>] [--style <style>] [--json]
• ow assets:get --asset-id <id> [--brand-id <id>] [--json]
• ow jobs:status --job-id <id> [--brand-id <id>] [--wait] [--json]
• ow permissions:get [--brand-id <id>] [--org-id <id>] [--base-url <url>] [--json]
• ow usage:get --brand-id <id> [--base-url <url>] [--json]
• ow generate:image --style-id <id> --prompt "..." [--brand-id <id>] [--wait] [--json]
• ow version:check [--fail-if-outdated] [--json]

Local Development

From repository root:

yarn cli:install
yarn openapi:generate
yarn cli:generate
yarn cli:lint
yarn cli:build

Run CLI commands from package directory:

cd packages/cli
node dist/bin/run.js --help
node dist/bin/run.js context:get --json

OpenAPI Sync

The CLI currently synchronizes from the app's embedded OpenAPI spec:

1. yarn spec:sync writes openapi/openapi.json
2. yarn client:types generates src/generated/api-types.ts

Combined:

yarn client:generate

Public Distribution (npmjs)

Package name: @openwonder/ow

Publish

Use the GitHub Actions workflow CLI Publish:

1. Update version in packages/cli/package.json and add a changelog entry in packages/cli/CHANGELOG.md.
2. Open Actions -> CLI Publish.
3. Run workflow (dry_run=true optional).
4. Ensure repository secret NPM_TOKEN is set (npm publish token).
5. On publish, workflow tags the release as ow-cli-v<version>.

Install On VPS (for OpenClaw)

Install and run:

npm install -g @openwonder/[email protected]
ow --help

Or pin and run without global install:

npx -y @openwonder/[email protected] --help

Version check in automation

ow version:check --json
ow version:check --fail-if-outdated

With --fail-if-outdated, exit code is 10 when a newer version exists in the registry.