CLI Commands

Choosing an environment

Every command that talks to the API needs to know which environment to target. The CLI never guesses — it resolves the mode from, in order:

1. --mode sandbox or --mode live
2. the OWOSTACK_MODE environment variable
3. the API key prefix: owo_sk_test_… → sandbox, owo_sk_live_… → live

With a legacy (unscoped) key and no --mode, the command exits with code 2 and tells you what to pass. If --mode contradicts the key's scope the command also refuses to run — before making any request.

--prod still works as a deprecated alias for --mode live.

Shared options

OWOSTACK_API_URL overrides the host for the selected mode (self-hosted / local API).

Exit codes

In --json mode failures are JSON too: { "ok": false, "error": { "code", "message", "hint?" }, "exitCode" }.

init

Scaffold owo.config.ts from your sandbox catalog. Runs connect first if no key is stored.

npx owosk init

connect

Link the CLI to your organization through the browser. One approval issues a sandbox key and a live key; commands pick the one matching --mode.

npx owosk connect

sync

Push your local catalog to the selected environment. Shows the diff and asks for confirmation unless --yes is passed.

npx owosk sync --mode sandbox
npx owosk sync --mode live --yes

Options:

• --dry-run: Show what would change without applying.
• --yes: Apply without the interactive prompt. Required together with --json.

CI example — preview, then apply:

OWOSTACK_SECRET_KEY=$SANDBOX_KEY npx owosk sync --dry-run --json
OWOSTACK_SECRET_KEY=$SANDBOX_KEY npx owosk sync --yes --json

--json output:

{
  "ok": true,
  "command": "sync",
  "mode": "sandbox",
  "apiUrl": "https://sandbox.owostack.com/api/v1",
  "dryRun": true,
  "hasChanges": true,
  "applied": false,
  "changes": {
    "plans": { "added": ["pro"], "removed": [], "changed": [] },
    "features": { "added": [], "removed": [], "changed": [] },
    "creditSystems": { "added": [], "removed": [], "changed": [] },
    "creditPacks": { "added": [], "removed": [], "changed": [] },
    "total": 1
  }
}

When changes are applied the document also carries "applied": true and the server's result (plans, features, creditSystems, creditPacks, warnings).

pull

Write the remote catalog for the selected environment into your local config.

npx owosk pull --mode sandbox

Options:

• --force: Overwrite an existing config file without asking.
• --dry-run: Print the generated config without writing it.

diff

Compare your local config with the remote catalog.

npx owosk diff --mode live
npx owosk diff --mode live --exit-code   # exit 3 on drift, for CI

Options:

• --exit-code: Exit with code 3 when the catalogs differ.

validate

Validate owo.config.ts locally and confirm the selected environment is reachable with your key.

npx owosk validate --mode sandbox