/wonda-cli

name: wonda-cli
description: Using the Wonda CLI to generate images, videos, music, and audio from the terminal — plus LinkedIn, Reddit, and X/Twitter research and automation

Wonda CLI

Wonda CLI is a content creation toolkit for terminal-based agents. Use it to generate images, videos, music, and audio; edit and compose media; publish to social platforms; and research/automate across LinkedIn, Reddit, and X/Twitter.

Install

If `wonda` is not found on PATH, install it first. The recommended installs are the signed desktop installers (CLI + tray icon + always-on relay, zero extra steps): macOS `brew install --cask degausai/tap/wonda-app` (or the wonda-macos.pkg from releases), Windows winget/wonda-windows-setup.exe. The CLI-only channels below work everywhere and can add the desktop app later with `wonda app install`:

# npm
npm i -g @degausai/wonda

# Homebrew
brew tap degausai/tap && brew install wonda

Setup

• **Auth**: `wonda auth login` (opens browser, recommended) or set `WONDA_API_KEY` env var
• **Verify**: `wonda auth check`

OAuth connector auth

Claude web and Cowork connectors use Wonda's OAuth 2.1 flow instead of a CLI API key field. The connector signs in through Wonda in the browser, grants the requested account access, and receives OAuth tokens bound to the Wonda API resource. The server swaps those tokens to the account's internal API key only inside Wonda, so agents and connector hosts never see the `sk_...` key. For the CLI and local stdio MCP path, keep using `wonda auth login` or `WONDA_API_KEY`.

Claude Cowork local relay

Claude Cowork (the desktop app) runs local MCP servers on the host, so it can load the `.mcpb` bundle or a local stdio `wonda-mcp` config directly, WAB writes included (verified 2026-07-07). Claude web cannot. The Wonda local relay is the alternative path: it lets the REMOTE connector (web or Cowork) run actions on the user's own Mac and residential IP without any local MCP config:

1. Open `https://wonda.sh/download` while signed in and install the notarized Mac package. 2. Pair the relay with `wonda relay pair` or the first-run browser handoff. This uses the existing `cli-auth` flow with a relay-scoped `wrelay_...` credential stored in the macOS Keychain. Do not ask the user to paste an API key or device code. 3. Open `https://wonda.sh/setup`, connect LinkedIn, X, and Reddit through the headful local WAB, then approve the Wonda connector once in Claude.

The engine policy is `auto | my_machine | cloud`. `auto` uses the local relay when it is online and cloud otherwise. `my_machine` must not silently fall back: if the relay is offline, ask whether to switch to cloud.

Organizations & spend context

Wondercat orgs are shared wallets with their own seats and billing. Members can spend from the org wallet (instead of their personal credits) by switching context:

• `wonda organizations list` (aliases: `wonda orgs list`, `wonda org list`) — see every org you belong to with your role and seat plan in each.
• `wonda use --org <slug>` — sticky org context for this machine. Sets

`X-Wonda-Org` on every request; holds, charges, and `wonda balance` route through the org wallet.

• `wonda use --personal` — back to personal.
• `wonda usage` — spend-only usage summary (total + per-model + per-project

breakdown) for a period (`--month 2026-05`, or `--from`/`--to`; defaults to the current month, UTC). `--project <name>` restricts the report to one project. In org context it reports org-wide usage including a per-member breakdown — admin/owner role required. Admins can also download a full Excel report from the org page on the web.

Projects (spend tagging)

Projects attribute spend to a named workstream for monitoring. Agents should check the active project at task start (`wonda use` prints it) and set one per task when the operator monitors spend by project:

• `wonda use --project <name>` — sticky: every subsequent charge carries

the project (in `wonda usage`, the API, and the org Excel report). `wonda use --no-project` stops tagging; switching org/personal context clears the project automatically (projects are per-scope).

• `--project <name>` on any command — one-off override for that invocation.
• `wonda project list|create|delete` — manage the registry in the active

scope. Org projects are created by org admins/owners only; personal projects are self-service. Tagging against a name that doesn't exist fails with `unknown_project` (no silent new buckets, so typos can't split the monitoring data).

`wonda topup` always tops up your **personal** wallet, regardless of context. Topping up the org wallet (and configuring auto top-up) is admin-only and happens on the web at `/organizations/<slug>`. If a member runs out of org credits, the error tells them to ask an admin or switch back to personal — they cannot top up the org wallet from CLI.

Roles inside an org are separate from the seat plan:

• **Owner**: the original creator. Cannot be demoted or kicked. Can transfer ownership to another member from the org page (rare).
• **Admin**: can invite (single or bulk via paste), kick, change roles, change seats, top up, configure auto top-up, change monthly limits.
• **User**: can only spend within the org wallet (subject to a per-member monthly limit if the admin set one).

A paid org seat (`WONDA` / `WONDA_PREMIUM`) grants the same paid feature access (skills, etc.) as a personal paid plan, but only while in org context. `wonda use --personal` falls back to the user's personal account plan.

Access tiers

Wonda is paid-only: every product surface requires a paid plan, including API calls, local platform reads, browser automation, media composition, file editing, diagnostics, generation, publishing, scraping, analysis, skills, relay operation, and cloud twin. Before any product command does work, the CLI performs a live entitlement check against Wonda. The check fails closed w