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:

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

### 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

Not all commands are available to every account type:

| Tier                                        | Access                                                                                                                                                                                                                                                                                                                                                                 |
| ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Anonymous** (temporary account, no login) | Media upload/download, transcription, social publishing, scraping, analytics. Editing ops (`wonda edit video/image/audio`) render locally via ffmpeg (no render credits); media download/upload still use the API.                                                                                                                                                     |
| **Free** (logged in, Basic/Free plan)       | Everything above + **generation** (`image/generate`, `video/generate`, etc.), styles, recipes, brand                                                                                                                                                                                                                                                                   |
| **Paid** (Plus, Pro, or Absolute plan)      | Everything above + **video analysis** (requires credits), **skill commands** (`wonda skill install/list/get`)                                                                                                                                                                                                                                                          |
| **Flagged** (per-account PostHog flags)     | `wonda transitions` (transitionsEnabled), `wonda clipping` (clippingEnabled), `wonda reddit signup` (redditAccountCreationEnabled). Flip the flag in PostHog for the account.                                                                                                                                                                                          |
| **Local** (no API call, no