degausai/wonda

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úsicas 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 desktop assinados (CLI + ícone na bandeja + relay sempre ativo, sem etapas extras): macOS brew install --cask degausai/tap/wonda-app (ou o wonda-macos.pkg dos lançamentos), Windows winget/wonda-windows-setup.exe. Os canais apenas CLI abaixo funcionam em qualquer lugar e podem adicionar o app desktop posteriormente 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 ambiente WONDA_API_KEY
• Verificar: wonda auth check

Autenticação via 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 do conector 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 stdio wonda-mcp diretamente, incluindo gravações WAB (verificado em 07/07/2026). O Claude web não consegue. 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 qualquer configuração MCP local:

1. Abra https://wonda.sh/download enquanto estiver logado e instale o pacote Mac notarizado.
2. Emparelhe o relay com wonda relay pair ou a transferência inicial do navegador. Isso usa o fluxo cli-auth existente com uma credencial com escopo de relay wrelay_... 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, depois 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 cloud caso contrário. my_machine não deve cair em fallback silenciosamente: se o relay estiver offline, pergunte se deseja alternar 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) alterando o contexto:

• wonda organizations list (sinônimos: wonda orgs list, wonda org list) — veja todas as organizações às quais você pertence, com seu papel 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 passam pela 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 de organização, relata o uso geral da 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)

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 o imprime) e definir um por tarefa quando o operador monitorar 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 para de marcar; alternar o contexto 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 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 para pedir a um administrador ou voltar para o contexto pessoal — ele não pode 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 (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 pago de organização (WONDA / WONDA_PREMIUM) concede o mesmo acesso a recursos pagos (habilidades, 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, habilidades, operação de relay e twin em nuvem. Antes de qualquer comando de produto realizar trabalho, o CLI faz uma verificação de direito de uso em tempo real contra o Wonda. A verificação falha fechada quando o acesso não pode ser verificado. Novas contas não têm acesso ao produto até se inscreverem, e um saldo de crédito positivo não substitui um plano.

Nível	Acesso
Anônimo (sem login)	Nenhum acesso ao produto. 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 se inscrever, recuperar ou parar serviços em segundo plano. Execute wonda auth login, depois inscreva-se.
Gratuito (logado, sem plano pago)	Nenhum acesso ao produto. Inscreva-se em https://wonda.sh/account para usar o produto.
WONDA (US$ 19,99/mês, "Pro")	Tudo, exceto twin em nuvem: geração (image/generate, video/generate, ...), upload/download de mídia, publicação, raspagem, análises, análise de vídeo, habilidades (wonda skill install/list/get), transições, clipe, e-mail, criação de conta no Reddit/LinkedIn, estilos, marca.
WONDA_PREMIUM (US$ 49,99/mês, "Premium")	Tudo no WONDA, mais twin em nuvem (wonda twin: provisionamento, execuções agendadas, login transmitido) com proteção antidetecção / shadowban, sem limites e criação de conta nos EUA.
Sinalizado (kill-switches PostHog por conta)	Incluído no plano pago, mas ainda bloqueável por um sinalizador por conta: wonda reddit signup (redditAccountCreationEnabled), wonda email (emailServerApiEnabled), enriquecimento de perfil público do LinkedIn (linkedinProfileEnrichmentEnabled).

Se um comando retornar 403 (paid_plan_required), inscreva-se 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 com 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: US$ 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 wonda existente
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 relata isExpired e expiresInDays)
wonda voice list

# Uma voz
wonda voice get <voice-id>

# Renomear / redescrever (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 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 forem usadas em TTS dentro de 7 dias são automaticamente expiradas. Executar TTS com uma voz clonada renova automaticamente sua expiração. Vozes ociosas que expirarem devem ser clonadas novamente (US$ 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 usando uma chave do lado do servidor e descriptografadas apenas no get.

# Criar
wonda credentials create --website instagram.com --username meuuser \
  --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 novouser

# Excluir
wonda credentials delete <id>

# Buscar + registrar por que está usando em uma única 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 no 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 — deduplique do seu lado se necessário.

Registro de eventos: todo credentials get/use, create, rotação de senha e outras atualizações são registrados 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 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 (habilitada automaticamente quando stdout é canalizado)
• --quiet — Apenas produz o identificador principal (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 depreciaçã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 depreciação, alertas de incidentes, prompts de atualização. As mensagens são impressas apenas no stderr, para que stdout/JSON permaneça limpo para canalização.

Dicas de depreciação por requisição chegam como o cabeçalho HTTP padrão Warning: 299 - "<mensagem>" e são exibidas no 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 1Password está incluído nos perfis WAB locais. O WAB baixa a extensão estável oficial do 1Password, verifica sua assinatura do editor e a fixa na barra de ferramentas na primeira configuração. Abra o WAB com wonda wab show <persona>, depois clique no 1Password para fazer login. Cada persona mantém sua própria sessão do 1Password. O aplicativo desktop pode exigir que você aprove o WAB como um navegador adicional; fazer login diretamente na extensão também funciona. Arquivos de extensão em cache funcionam offline. O WAB verifica atualizações de extensões em cache no máximo uma vez por dia quando uma persona é iniciada, incluindo verificações com falha; alterar a versão do Chromium aciona outra verificação de compatibilidade. Se a extensão nunca foi instalada com sucesso, cada início tenta a instalação novamente. Um navegador já em execução capta uma atualização de extensão em seu próximo início. A inicialização e wab install removem versões em cache não utilizadas com mais de sete dias; versões usadas por um processo WAB ativo são mantidas. Defina WAB_ONEPASSWORD=0 antes de iniciar o WAB para pular a extensão agrupada. Capturas anônimas, sessões temporárias e twins em nuvem não a carregam. Um caminho de dados do Wonda contendo uma vírgula também pula o 1Password com um dr

…

[truncado para tradução]