Wonda CLI
O 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. As instalações recomendadas são os instaladores de desktop assinados (CLI + ícone na bandeja + relay sempre ativo, zero etapas extras): macOS brew install --cask degausai/tap/wonda-app (ou o wonda-macos.pkg dos releases), Windows winget/wonda-windows-setup.exe. Os canais apenas CLI abaixo funcionam em qualquer lugar e podem adicionar o aplicativo de desktop depois com wonda app install:
# 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 ambienteWONDA_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 solicitado à conta 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 (aplicativo de desktop) executa servidores MCP locais no host, então pode carregar o pacote .mcpb ou uma configuração wonda-mcp stdio local diretamente, incluindo gravações WAB (verificado em 2026-07-07). O Claude web não pode. O relay local do Wonda é o caminho alternativo: ele permite que o conector REMOTO (web ou Cowork) execute ações no próprio Mac do usuário e no IP residencial sem nenhuma configuração MCP local:
- Abra
https://wonda.sh/downloadenquanto estiver logado e instale o pacote Mac notarizado. - Emparelhe o relay com
wonda relay pairou a transferência de navegador na primeira execução. Isso usa o fluxocli-authexistente com uma credencialwrelay_...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. - 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 de engine é auto | my_machine | cloud. auto usa o relay local quando está online e cloud caso contrário. my_machine não deve cair em fallback silenciosamente: se o relay estiver offline, pergunte se deseja mudar para cloud.
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) mudando de contexto:
wonda organizations list(aliases:wonda orgs list,wonda org list) — veja cada organização da qual você faz parte com sua função e plano de assento em cada uma.wonda use --org <slug>— contexto de organização fixo para esta máquina. DefineX-Wonda-Orgem cada requisição; retenções, cobranças ewonda balanceroteiam através da carteira da organização.wonda use --personal— volta ao pessoal.wonda usage— resumo de uso apenas de gastos (total + por modelo + por projeto) para um período (--month 2026-05, ou--from/--to; 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 — função de administrador/proprietário necessária. Administradores também podem baixar um relatório completo em Excel da página da organização na web.
Projetos (marcação de gastos)
Projetos atribuem gastos a um fluxo de trabalho nomeado para monitoramento. Agentes devem verificar o projeto ativo no início da tarefa (wonda use o imprime) e definir um por tarefa quando o operador monitora gastos por projeto:
wonda use --project <name>— fixo: toda cobrança subsequente carrega o projeto (emwonda usage, na API e no relatório Excel da organização).wonda use --no-projectpara de marcar; mudar o contexto de organização/pessoal limpa o projeto automaticamente (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. Projetos de 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 comunknown_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 para pedir a um administrador ou voltar ao pessoal — eles não podem recarregar a carteira da organização pelo 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 pela página da organização (raro).
- Administrador: pode convidar (individual ou em lote via colagem), remover, mudar funções, mudar assentos, recarregar, configurar recarga automática, alterar limites mensais.
- Usuário: pode apenas 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 requer um plano pago, incluindo chamadas de API, leituras de plataforma local, automação de navegador, composição de mídia, edição de arquivos, diagnósticos, geração, publicação, raspagem, análise, skills, operação de relay e cloud twin. Antes de qualquer comando de produto realizar trabalho, o CLI realiza uma verificação de direito de acesso ao vivo contra o Wonda. A verificação falha fechada quando o acesso não pode ser verificado. Novas contas não têm acesso a produtos até assinarem, e um saldo de crédito positivo não substitui um plano.
| Nível | Acesso |
|---|---|
| Anônimo (sem login) | Nenhum acesso a produtos. Comandos de autenticação, configuração, preços, descoberta/seleção de organização, conclusão de shell e desligamento local permanecem disponíveis para que o usuário possa assinar, recuperar ou parar serviços em segundo plano. Execute wonda auth login, depois assine. |
| Gratuito (logado, sem plano pago) | Nenhum acesso a produtos. Assine em https://wonda.sh/account para usar o produto. |
WONDA ($19,99/mês, "Pro") | Tudo exceto cloud twin: 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, corte, email, criação de conta reddit/linkedin, estilos, marca. |
WONDA_PREMIUM ($49,99/mês, "Premium") | Tudo no WONDA, mais cloud twin (wonda twin: provisionamento, execuções agendadas, login transmitido) com proteção antidetect / shadowban, sem limites e criação de conta nos EUA. |
| Sinalizado (kill-switches por conta PostHog) | Incluído no plano pago, mas ainda bloqueável por uma flag por conta: wonda reddit signup (redditAccountCreationEnabled), wonda email (emailServerApiEnabled), enriquecimento de perfil público do LinkedIn (linkedinProfileEnrichmentEnabled). |
Se um comando retornar um 403 (paid_plan_required), assine em https://wonda.sh/account.
Isso se aplica também ao caminho MCP stdio local porque o MCP executa o mesmo CLI. Cookies e dados da plataforma permanecem no dispositivo, mas o comando deve primeiro receber uma decisão de acesso pago bem-sucedida de GET /api/v1/auth/access. Uma instalação apenas relay pode usar sua credencial wrelay_... com escopo para essa verificação de direito. A credencial com escopo ainda não pode chamar APIs de conta comuns.
Clonagem de voz
Clone uma voz a partir de um clipe de áudio de 10s+ e use-a em TTS. Limite máximo: 20 vozes clonadas por conta. Custo: $1,50 por clone.
# Clonar 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 de mídia existente do wonda
wonda voice create "Marca" --media-id <uuid>
# Pré-processamento opcional do áudio de origem
wonda voice create "Limpa" --file ./raw.wav --noise-reduction --normalize-volume
# Listar vozes clonadas (cada linha informa isExpired e expiresInDays)
wonda voice list
# Uma voz
wonda voice get <voice-id>
# Renomear / re-descrever (local apenas, sem chamada ao provedor)
wonda voice update <voice-id> --name "Novo Nome" --description "..."
# Deletar
wonda voice delete <voice-id>
Use uma voz clonada em 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 são usadas em TTS dentro de 7 dias são expiradas automaticamente. Executar TTS com uma voz clonada renova automaticamente sua expiração. Vozes ociosas que expiram devem ser clonadas novamente ($1,50 novamente).
Cofre de credenciais
Persista 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 apenas descriptografadas em get.
# Criar
wonda credentials create --website instagram.com --username meuhandle \
--email [email protected] --password-stdin <<< "hunter2" \
--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 novohandle
# Deletar
wonda credentials delete <id>
# Buscar + registrar por que você está usando em uma chamada — POST, não GET, porque
# escreve um evento 'usado' 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. Vários registros por (website, username) são permitidos — deduplique do seu lado se necessário.
Registro de eventos: toda credentials get/use, create, rotação de password 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 da web UI para auditar. O registro de eventos é somente anexação e cascateia 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 é redirecionado)--quiet— Apenas saída do identificador primário (ID do job, ID da mídia, etc.) — ideal para scripts-o <caminho>— 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 do 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 em stderr, então stdout/JSON permanece limpo para redirecionamento.
Dicas de descontinuação por requisição chegam como o cabeçalho HTTP padrão Warning: 299 - "<mensagem>" e são exibidas em stderr pelo cliente HTTP do CLI como [deprecated METHOD /path] <mensagem>.
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 antidetect stealth premium, endurecido para que as plataformas não possam identificá-lo como automação. wonda wab é o único comando para a pilha Chromium antidetect (um fork do Playwright não detectado). Ele tem duas faces:
- Sessões autenticadas. Um Chromium headful persistente por persona que mantém sessões logadas para LinkedIn, X, Reddit e outros. O CLI o inicia sob demanda, deixa-o ocioso e roteia leituras/escritas 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>(ewonda brand extract) dirigem um Chromium efêmero com uma fingerprint nova, sem persona, sem cookies. Veja o blocorecordabaixo.
O modelo mental: você tem contas (uma identidade por plataforma). Cada comando de plataforma roteia para os cookies daquela conta através do armazenamento JSON simples (--via cookies, rápido, sem Chromium) ou da persona da conta (--via wab, Chromium antidetect ao vivo). Uma persona é o invólucro Chromium que pode conter várias contas sob uma fingerprint. Em um
…
[truncado para tradução]