Wonda CLI

O que Wonda CLI faz?

Wonda CLI é um kit de ferramentas de criação de conteúdo para agentes baseados em terminal. Use-o para gerar imagens, vídeos, música e áudio; editar e compor mídia; publicar em plataformas sociais; e pesquisar/automatizar no LinkedIn, Reddit e X/Twitter.

Instalação

Se wonda não for encontrado no PATH, instale-o primeiro:

# npm
npm i -g @degausai/wonda

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

Configuração

• Autenticação: wonda auth login (abre o navegador, recomendado) ou defina a variável de ambiente WONDA_API_KEY
• Verificar: wonda auth check

Autenticação do conector OAuth

Os conectores Claude web e Cowork usam o fluxo OAuth 2.1 do Wonda em vez de um campo de chave de API no CLI. O conector faz login através do Wonda no navegador, concede o acesso à conta solicitado e recebe tokens OAuth vinculados ao recurso da API Wonda. O servidor troca esses tokens pela chave de API interna da conta apenas dentro do Wonda, então agentes e hosts de conectores nunca veem a chave sk_.... Para o CLI e o caminho MCP stdio local, continue usando wonda auth login ou WONDA_API_KEY.

Relay local do Claude Cowork

O Claude Cowork (o aplicativo desktop) executa servidores MCP locais no host, então ele pode carregar o pacote .mcpb ou uma configuração local wonda-mcp stdio diretamente, incluindo gravações WAB (verificado em 2026-07-07). O Claude web não pode. O relay local Wonda é o caminho alternativo: ele permite que o conector REMOTO (web ou Cowork) execute ações no próprio Mac do usuário e IP residencial sem nenhuma configuração MCP local:

1. Abra https://wonda.sh/download enquanto estiver conectado e instale o pacote Mac notarizado.
2. Emparelhe o relay com wonda relay pair ou a transferência de navegador na primeira execução. Isso usa o fluxo cli-auth existente com uma credencial wrelay_... com escopo de relay armazenada no Keychain do macOS. Não peça ao usuário para colar uma chave de API ou código de dispositivo.
3. Abra https://wonda.sh/setup, conecte LinkedIn, X e Reddit através do WAB local headful, e então aprove o conector Wonda uma vez no Claude.

A política do mecanismo é auto | my_machine | cloud. auto usa o relay local quando está online e a nuvem caso contrário. my_machine não deve cair em fallback silenciosamente: se o relay estiver offline, pergunte se deve mudar para a nuvem.

Organizações e contexto de gastos

As organizações Wondercat são carteiras compartilhadas com seus próprios assentos e faturamento. Os membros podem gastar da carteira da organização (em vez de seus créditos pessoais) alternando o contexto:

• wonda organizations list (aliases: wonda orgs list, wonda org list) — veja todas as organizações às quais você pertence com sua função e plano de assento em cada uma.
• wonda use --org <slug> — contexto de organização fixo para esta máquina. Define X-Wonda-Org em cada requisição; retenções, cobranças e wonda balance são roteados através da carteira da organização.
• wonda use --personal — volta para o contexto pessoal.
• wonda usage — resumo de uso apenas de gastos (total + por modelo + por projeto) para um período (--month 2026-05, ou --from/--to; o padrão é o mês atual, UTC). --project <name> restringe o relatório a um projeto. No contexto da organização, relata o uso em toda a organização, incluindo um detalhamento por membro — requer função de administrador/proprietário. Os administradores também podem baixar um relatório completo em Excel da página da organização na web.

Projetos (marcação de gastos)

Os projetos atribuem gastos a um fluxo de trabalho nomeado para monitoramento. Os agentes devem verificar o projeto ativo no início da tarefa (wonda use exibe) e definir um por tarefa quando o operador monitora gastos por projeto:

• wonda use --project <name> — fixo: cada cobrança subsequente carrega o projeto (em wonda usage, na API e no relatório Excel da organização). wonda use --no-project interrompe a marcação; alternar o contexto de organização/pessoal limpa o projeto automaticamente (os projetos são por escopo).
• --project <name> em qualquer comando — substituição única para aquela invocação.
• wonda project list|create|delete — gerencia o registro no escopo ativo. Os projetos da organização são criados apenas por administradores/proprietários da organização; projetos pessoais são autoatendidos. Marcar contra um nome que não existe falha com unknown_project (sem novos buckets silenciosos, então erros de digitação não podem dividir os dados de monitoramento).

wonda topup sempre recarrega sua carteira pessoal, independentemente do contexto. Recarregar a carteira da organização (e configurar recarga automática) é apenas para administradores e acontece na web em /organizations/<slug>. Se um membro ficar sem créditos da organização, o erro informa que ele deve pedir a um administrador ou voltar ao contexto pessoal — eles não podem recarregar a carteira da organização a partir do CLI.

As funções dentro de uma organização são separadas do plano de assento:

• Proprietário: o criador original. Não pode ser rebaixado ou removido. Pode transferir a propriedade para outro membro a partir da página da organização (raro).
• Administrador: pode convidar (individualmente ou em lote via colagem), remover, alterar funções, alterar assentos, recarregar, configurar recarga automática, alterar limites mensais.
• Usuário: só pode gastar dentro da carteira da organização (sujeito a um limite mensal por membro, se o administrador definiu um).

Um assento de organização pago (WONDA / WONDA_PREMIUM) concede o mesmo acesso a recursos pagos (skills, etc.) que um plano pessoal pago, mas apenas no contexto da organização. wonda use --personal volta ao plano da conta pessoal do usuário.

Níveis de acesso

O Wonda é pago: toda superfície de produto (geração, mídia, publicação, raspagem, análise, skills, gêmeo na nuvem) requer um plano pago. Novas contas não recebem créditos e nenhum acesso ao produto até assinarem.

Nível	Acesso
Anônimo (conta temporária, sem login)	Sem acesso ao produto. O CLI cria uma conta temporária na primeira execução, mas atinge apenas os comandos locais abaixo mais os endpoints de autenticação/faturamento. Execute wonda auth login e depois assine.
Gratuito (logado, sem plano pago)	Sem acesso ao produto. Assine em https://wonda.sh/account para usar o produto.
WONDA ($19.99/mês, "Pro")	Tudo exceto gêmeo na nuvem: geração (image/generate, video/generate, ...), upload/download de mídia, publicação, raspagem, análises, análise de vídeo, skills (wonda skill install/list/get), transições, clipes, e-mail, criação de contas reddit/linkedin, estilos, marca.
WONDA_PREMIUM ($49.99/mês, "Premium")	Tudo no WONDA, mais gêmeo na nuvem (wonda twin: provisionamento, execuções agendadas, login em streaming) com proteção antidetecção / shadowban, sem limites e criação de contas nos EUA.
Sinalizado (kill-switches PostHog por conta)	Incluído no plano pago, mas ainda controlável por um sinalizador por conta: wonda reddit signup (redditAccountCreationEnabled), wonda email (emailServerApiEnabled), enriquecimento de perfil público do LinkedIn (linkedinProfileEnrichmentEnabled).
Local (sem chamada de API, sem créditos, sem plano)	Executado inteiramente na sua máquina, então funciona sem plano: wonda brand extract <url> (sem --save), wonda compose motion/wonda compose text, wonda wab record <url>, wonda edit ... transformações ffmpeg primitivas em arquivos locais e wonda doctor. Os baseados em Chromium precisam de uma instalação única wonda wab install.

Se um comando retornar 403 (paid_plan_required), assine em https://wonda.sh/account.

Clonagem de voz

Clone uma voz a partir de um clipe de áudio de 10s+ e use-a em TTS. Limite rígido: 20 vozes clonadas por conta. Custo: $1,50 por clone.

# Clonar a partir de um arquivo local (faz upload automático para a biblioteca de mídia primeiro)
wonda voice create "Andu" --file ./sample.mp3 --description "Minha voz"

# Clonar a partir de mídia wonda existente
wonda voice create "Marca" --media-id <uuid>

# Pré-processamento de áudio de origem opcional
wonda voice create "Limpa" --file ./raw.wav --noise-reduction --normalize-volume

# Listar vozes clonadas (cada linha relata isExpired e expiresInDays)
wonda voice list

# Uma voz
wonda voice get <voice-id>

# Renomear / re-descrever (apenas local, sem chamada ao provedor)
wonda voice update <voice-id> --name "Novo Nome" --description "..."

# Excluir
wonda voice delete <voice-id>

Use uma voz clonada no TTS passando o providerVoiceId de voice get como voiceId para /audio/speech:

wonda audio speech "Olá mundo" \
  --model minimax-speech-2-8-hd \
  --params '{"voiceId":"<providerVoiceId>"}'

Expiração de 7 dias: vozes clonadas que não forem usadas em TTS dentro de 7 dias são expiradas automaticamente. Executar TTS com uma voz clonada atualiza automaticamente sua expiração. Vozes ociosas que expiram devem ser clonadas novamente ($1,50 novamente).

Cofre de credenciais

Persiste logins criados em plataformas externas (Instagram, TikTok, Twitter, etc.) para que possam ser reutilizados na próxima execução. As senhas são criptografadas com AES-256-GCM com uma chave do lado do servidor e só descriptografadas em get.

# Criar
wonda credentials create --website instagram.com --username meuusuario \
  --email [email protected] --password-stdin <<< "senha123" \
  --metadata '{"signup_source":"wonda-email"}'

# Listar (senhas omitidas)
wonda credentials list --website instagram.com

# Obter registro completo, incluindo senha descriptografada
wonda credentials get <id>

# Atualizar qualquer campo (use --password-stdin para rotacionar; --username "" para limpar)
wonda credentials update <id> --username novousuario

# Excluir
wonda credentials delete <id>

# Buscar + registrar por que está usando em uma única chamada — POST, não GET, porque
# escreve um evento 'used' com o motivo. Prefira isso a `get` sempre que
# puder articular o motivo.
wonda credentials use <id> --reason "fluxo de cadastro instagram"

# Ver eventos recentes (criado / usado / rotacionado / atualizado) para auditoria
wonda credentials events <id>

Campos: website (obrigatório — entrada digitada como insta é canonicalizada para instagram.com), username, email, password (obrigatório), metadata (JSON arbitrário). Pelo menos um de username / email deve estar presente. Múltiplos registros por (website, username) são permitidos — deduplicação por sua conta se necessário.

Registro de eventos: cada credentials get/use, create, rotação de senha e outras atualizações são registradas como eventos na credencial (ator: cli | web | system). Use credentials events <id> ou o ícone de histórico na interface web para auditar. O registro de eventos é somente anexação e é excluído em cascata na exclusão da credencial.

Flags globais de saída

Todos os comandos suportam estas flags de controle de saída:

• --json — Força saída JSON (ativada automaticamente quando stdout é pipe)
• --quiet — Apenas a saída do identificador primário (ID do job, ID da mídia, etc.) — ideal para scripts
• -o <path> — Baixa a saída para um arquivo (implica --wait)
• --fields status,outputs — Seleciona campos JSON específicos
• --jq '.outputs[0].media.url' — Filtra a saída JSON com uma expressão jq

Anúncios CLI e avisos de descontinuação

Em cada comando, o CLI consulta GET /api/v1/updates (anônimo, cache de 1h em ~/.wonda/state.json) por anúncios ativos: avisos de descontinuação, alertas de incidentes, prompts de atualização. As mensagens são impressas apenas no stderr, então stdout/JSON permanece limpo para pipes.

Dicas de descontinuação por requisição chegam como o cabeçalho HTTP padrão Warning: 299 - "<message>" e são exibidas no stderr pelo cliente HTTP do CLI como [deprecated METHOD /path] <message>.

Silencie ambos os canais com WONDA_QUIET=1 (variável de ambiente) ou --quiet (flag). Desabilite apenas as verificações de rede com WONDA_NO_UPDATE_CHECK=1.

WAB / Wonda Automation Browser (wonda wab)

O Wonda Automation Browser (WAB) é um navegador antidetecção furtivo premium, endurecido para que as plataformas não possam identificá-lo como automação. wonda wab é o comando único para a pilha Chromium antidetecção (um fork do Playwright não detectado). Tem duas faces:

• Sessões autenticadas. Um Chromium headful persistente por persona que mantém sessões logadas para LinkedIn, X, Reddit e amigos. O CLI o inicia sob demanda, deixa-o ocioso e roteia leituras/gravações da plataforma através dele sempre que um comando executa --via wab. Os cookies vivem no perfil Chromium da persona, não em ~/.wonda/config.json.
• Captura anônima. wonda wab record <url> (e wonda brand extract) dirige um Chromium efêmero com uma impressão digital nova, sem persona, sem cookies. Veja o bloco record abaixo.

O modelo mental: você tem contas (uma identidade por plataforma). Cada comando de plataforma roteia para os cookies dessa conta através do armazenamento JSON simples (--via cookies, rápido, sem Chromium) ou da persona da conta (--via wab, Chromium antidetecção ao vivo). Uma persona é o invólucro Chromium que pode conter múltiplas contas sob uma impressão digital. Em quase todos os casos, a persona é criada automaticamente no primeiro uso de --via wab, nomeada após a conta, então você nunca digita um nome de persona.

A extensão de desktop local wonda.mcpb usa este mesmo caminho WAB local do Claude Desktop ou Claude Code: os cookies da plataforma permanecem no dispositivo, as leituras usam cookies locais e as gravações usam o WAB local. Claude web e Cowork precisam do conector MCP remoto.

Login nativo