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`:

```bash
# 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 carr