Wonda CLI

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.

1. 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.

1. 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 — 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 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 — 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 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/. 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, or an existing WONDA_PREMIUM seat) 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, and relay operation. Before any product command does work, the CLI performs a live entitlement check against Wonda. The check fails closed when access cannot be verified. If that entitlement GET receives HTTP 429, the CLI waits once for a valid Retry-After (seconds or HTTP date), or 60 seconds when absent/invalid, then retries only the entitlement GET. Automatic waiting is capped at 60 seconds: a longer server delay fails closed immediately and reports its earliest suggested next attempt. Cancellation, a terminal deny/error, or an unconfirmed response blocks product work. A terminal 429 reports the exhausted retry and earliest suggested next attempt, not a guaranteed reset time. Successful access is never cached, and product mutations are never replayed by this recovery. New accounts get no product access until they subscribe, and a positive credit balance does not substitute for a plan.

Tier	Access
Anonymous (no login)	No product access. Authentication, config, pricing, organization discovery/selection, shell completion, and local shutdown commands remain available so the user can subscribe, recover, or stop background services. Run wonda auth login, then subscribe.
Free (logged in, no paid plan)	No product access. Subscribe at https://wonda.sh/account to use the product.
WONDA ($49.99/mo, Pro)	The one plan. New subscribers pay $49.99/mo; existing subscribers keep the price they signed up at. Generation (image/generate, video/generate, ...) is billed per use from the credit balance: the plan includes no generation credits. Also media upload/download, publishing, scraping, analytics, video analysis, skills (wonda skill install/list/get), transitions, clipping, email, reddit/linkedin account creation, styles, brand.
WONDA_PREMIUM (Premium, parked)	No longer sold. Existing Premium subscribers keep their plan and cloud twin (wonda twin) access; cloud twins are not offered to anyone else.
Flagged (per-account PostHog kill-switches)	Included in the paid plan but still gateable by a per-account flag: wonda reddit signup (redditAccountCreationEnabled), wonda email (emailServerApiEnabled), public LinkedIn profile enrichment (linkedinProfileEnrichmentEnabled).

If a command returns a 403 (paid_plan_required), subscribe at https://wonda.sh/account.

This applies to the local stdio MCP path too because MCP executes the same CLI. Platform cookies and data remain on-device, but the command must first receive a successful paid-access decision from GET /api/v1/auth/access. A relay-only installation may use its scoped wrelay_... credential for that entitlement probe. The scoped credential still cannot call ordinary account APIs.

Voice cloning

Clone a voice from a 10s+ audio clip and use it in TTS. Hard limit: 20 cloned voices per account. Cost: $1.50 per clone.

# Clone from a local file (auto-uploads to media library first)
wonda voice create "Andu" --file ./sample.mp3 --description "My voice"

# Clone from existing wonda media
wonda voice create "Brand" --media-id 

# Optional source-audio preprocessing
wonda voice create "Clean" --file ./raw.wav --noise-reduction --normalize-volume

# List cloned voices (each row reports isExpired and expiresInDays)
wonda voice list

# One voice
wonda voice get 

# Rename / re-describe (local only, no provider call)
wonda voice update  --name "New Name" --description "..."

# Delete
wonda voice delete

Use a cloned voice in TTS by passing the providerVoiceId from voice get as voiceId to /audio/speech:

wonda audio speech "Hello world" \
  --model minimax-speech-2-8-hd \
  --params '{"voiceId":""}'

7-day expiry: cloned voices that haven't been used in TTS within 7 days are automatically expired. Running TTS with a cloned voice automatically refreshes its expiry. Idle voices that lapse must be re-cloned ($1.50 again).

Credentials vault

Persist logins created on external platforms (Instagram, TikTok, Twitter, etc.) so they can be reused on the next run. Passwords are AES-256-GCM encrypted with a server-side key and only decrypted on get.

# Create
wonda credentials create --website instagram.com --username myhandle \
  --email me@example.com --password-stdin <<< "hunter2" \
  --metadata '{"signup_source":"wonda-email"}'

# List (passwords omitted)
wonda credentials list --website instagram.com

# Get full record including decrypted password
wonda credentials get 

# Update any field (use --password-stdin to rotate; --username "" to clear)
wonda credentials update  --username newhandle

# Delete
wonda credentials delete 

# Fetch + record why you're using it in one call — POST, not GET, because
# it writes a 'used' event with the reason. Prefer this over `get` whenever
# you can articulate the reason.
wonda credentials use  --reason "instagram signup flow"

# See recent events (created / used / rotated / updated) for audit
wonda credentials events

Fields: website (required — typed input like insta is canonicalized to instagram.com), username, email, password (required), metadata (arbitrary JSON). At least one of username / email must be present. Multiple records per (website, username) are allowed — dedupe on your side if you need to.

Event log: every credentials get/use, create, password rotate, and other updates are recorded as events on the credential (actor: cli | web | system). Use credentials events or the web UI's history icon to audit. The event log is append-only and cascades on credential delete.

Global output flags

All commands support these output control flags:

• --json — Force JSON output (auto-enabled when stdout is piped)
• --quiet — Only output the primary identifier (job ID, media ID, etc.) — ideal for scripting
• -o — Download output to file (implies --wait)
• --fields status,outputs — Select specific JSON fields
• --jq '.outputs[0].media.url' — Filter JSON output with a jq expression

CLI announcements & deprecation warnings

On every command the CLI polls GET /api/v1/updates (anonymous, 1h cache in ~/.wonda/state.json) for active announcements: deprecation notices, incident heads-ups, upgrade prompts. Messages are printed to stderr only, so stdout/JSON stays clean for piping.

Per-request deprecation hints arrive as the standard Warning: 299 - "" HTTP header and are surfaced to stderr by the CLI's HTTP client as [deprecated METHOD /path] .

Silence both channels with WONDA_QUIET=1 (env var) or --quiet (flag). Disable just the network checks with WONDA_NO_UPDATE_CHECK=1.

WAB / Wonda Automation Browser (wonda wab)

Claude/Codex and other agent launches default to background. Use wonda wab start and normal platform commands without --visible; this matches the Dock menu's Send to background state. Show a WAB only for an intentional visible inspection or manual login. wab show/hide affects the current session and never changes the next launch default. wab config set visible true is a deliberate persistent opt-in. Routine reuse preserves visibility and the selected tab, and showing the window preserves that tab too.

Local CAPTCHA/authentication detection reports the blocker without surfacing the browser or taking keyboard focus. Notify the operator through their authorized channel and provide the exact wonda wab show command; let them choose when to show it. Explicit show/login commands and hosted streamed login remain visible as requested.

From CLI v1.66.0, macOS persona visibility uses AppKit without per-persona Automation prompts. WAB hides, shows and activates its own browser app by PID without sending Apple Events to System Events or the persona app. This also covers the native-host fallback guard. An already-running older driver keeps its old guard until that persona is restarted at a safe time; coordinate with its owner before restarting an active session.

1Password is included in local WAB profiles. WAB downloads the official stable 1Password browser extension, verifies its publisher signature, and pins it to the toolbar on first setup. Open the WAB with wonda wab show , then click 1Password to sign in. Each persona keeps its own 1Password session. The desktop app may require you to approve WAB as an additional browser; signing in directly in the extension also works. Cached extension files work offline. WAB checks cached extensions for updates at most once a day when a persona starts, including failed checks; changing the Chromium version triggers another compatibility check. If the extension has never installed successfully, each start retries installation. An already-running browser picks up an extension update on its next start. When the bundled extension changes, WAB refreshes its background service worker so Chromium cannot reuse code from the previous version. This preserves the persona’s 1Password sign-in and vault data. Startup and wab install prune unused cached versions older than seven days; versions used by a live WAB process are kept. Set WAB_ONEPASSWORD=0 before starting WAB to skip the bundled extension. Anonymous captures, scratch sessions, and cloud twins do not load it. A Wonda data path containing a comma also skips 1Password with a driver-log warning; use a WONDA_HOME path without commas to enable the extension. Enhanced Safe Browsing or administrator policies can also block automatic extension loading; WAB reports Chromium’s rejection in its driver log and preserves your browser settings.

WAB has Google Chrome's speech voices. Chrome for Testing, the browser inside the WAB, lacks the 19 Google ... voices Google Chrome lists in speechSynthesis.getVoices(), which bot detectors read as a non-Chrome build. WAB bundles a small extension with Chrome's own key and voice list, loaded in every session (personas, scratch and cloud). The voices report start and end like Google's, without audio (the WAB is muted). Set WAB_NETWORK_SPEECH=0 before starting a persona to skip it. WAB also keeps Chrome's media router on (Playwright disables it by default, which pages can detect).

Browser defaults and migration. New local macOS personas use Google's stable Chrome. Existing personas keep their recorded browser, or Chrome for Testing when they have no browser history. Upgrading the CLI never migrates them. Linux, Windows and cloud runners use Chrome for Testing for new personas. wonda wab config set browser chromium explicitly pins Chrome for Testing; browser chrome opts a stopped Mac persona into Chrome after backing up its profile and checking version compatibility. WAB_BROWSER overrides the pin. wonda wab config get effective_browser reports the resolved choice; whole-config JSON includes this read-only field alongside any explicit browser pin. Unsetting browser preserves the last recorded browser. Fresh scratch profiles use the platform default; existing custom profiles without browser history retain the legacy Chrome for Testing choice, and new custom-profile choices persist with the profile even when scratch artifacts are removed. In our tests FingerprintJS Pro flagged Chrome for Testing as an anti-detect browser in most fresh sessions and Google Chrome in none. On the persona's first start the WAB downloads Chrome from Google (about 280 MB), checks Google's signature, removes its auto-updater keys and re-signs a private copy, so it never touches or updates your own Chrome. Each persona gets its own Wonda-branded clone that runs in the background like before, and 1Password loads as usual. wonda wab update moves the copy to the latest stable Chrome, and wonda wab doctor shows which browser a persona runs. Once a persona has run Chrome, keep it there: going back to an older Chromium drops the profile's IndexedDB, so 1Password would need signing in again.

The Wonda Automation Browser (WAB) is a premium stealth antidetect browser, hardened so platforms cannot fingerprint it as automation. wonda wab is the one command for the antidetect Chromium stack (an undetected Playwright fork). It has two faces:

• Authenticated sessions. One persistent headful Chromium per persona that holds sig