manodhithyaa-dev/GraphCode

wonda-cli

Visão Geral

Usando a CLI da Wonda para gerar imagens, vídeos, música e áudio diretamente do terminal — além de pesquisa e automação no LinkedIn, Reddit e X/Twitter

Fluxo de Trabalho

---

name: wonda-cli description: Usando a CLI da Wonda para gerar imagens, vídeos, música e áudio do terminal — além de pesquisa e automação no LinkedIn, Reddit e X/Twitter

Wonda CLI

A Wonda CLI é um kit de ferramentas de criação de conteúdo para agentes baseados em terminal. Use-a 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
• Verificação: wonda auth check

Autenticação do conector OAuth

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

Relay local do Claude Cowork

O Claude Cowork (aplicativo desktop) executa servidores MCP locais no host, então ele pode carregar o pacote .mcpb ou uma configuração stdio local wonda-mcp diretamente, com suporte a WAB incluso (verificado em 2026-07-07). O Claude web não pode. O relay local da 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 local de MCP:

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 troca 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 completo, 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 cloud caso contrário. my_machine não deve cair em fallback silencioso: se o relay estiver offline, pergunte se deseja mudar para cloud.

Contexto de organizações e gastos

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

• wonda organizations list (aliases: wonda orgs list, wonda org list) — veja cada org da qual você faz parte com sua função e plano de assento em cada uma.
• wonda use --org <slug> — contexto de org persistente 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 org.
• wonda use --personal — volta para o modo 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 para o mês atual, UTC). --project <name> restringe o relatório a um projeto. No contexto da org, ele reporta o uso geral da org incluindo um detalhamento por membro — função de admin/owner necessária. Admins também podem baixar um relatório completo em Excel da página da org na web.

Projetos (tagging 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 exibe) e definir um por tarefa quando o operador monitorar gastos por projeto:

• wonda use --project <name> — persistente: cada cobrança subsequente carrega o projeto (em wonda usage, na API e no relatório Excel da org). wonda use --no-project para de marcar; alternar o contexto org/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 da org são criados apenas por admins/owners da org; projetos pessoais são autoatendidos. Marcar contra um nome que não existe falha com unknown_project (sem novos buckets silenciosos, para que erros de digitação não dividam os dados de monitoramento).

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

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

• Owner: o criador original. Não pode ser rebaixado ou removido. Pode transferir a propriedade para outro membro pela página da org (raro).
• Admin: pode convidar (individualmente ou em massa por colagem), remover, alterar funções, alterar assentos, recarregar, configurar recarga automática, alterar limites mensais.
• User: pode apenas gastar dentro da carteira da org (sujeito a um limite mensal por membro se o admin definiu um).

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

Níveis de acesso

A Wonda é paga apenas: toda superfície de produto (geração, mídia, publicação, scraping, análise, skills, cloud twin) 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. A CLI cria uma conta temporária na primeira execução, mas ela atinge apenas os comandos locais abaixo mais os endpoints de autenticação/faturamento. Execute wonda auth login, depois assine.
Grátis (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 cloud twin: geração (image/generate, video/generate, ...), upload/download de mídia, publicação, scraping, análise, análise de vídeo, skills (wonda skill install/list/get), transições, clipping, e-mail, criação de contas no 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 antidetecção / 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).
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 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 da wonda
wonda voice create "Marca" --media-id <uuid>

# Pré-processamento opcional do áudio fonte
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 (apenas local, 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 forem usadas em TTS em até 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 ($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 só 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 ao `get` sempre que puder
# articular o motivo.
wonda credentials use <id> --reason "fluxo de cadastro do instagram"

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

Campos: website (obrigatório — entrada digitada como insta é canonizada 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 — desduplique do seu lado se necessário.

Registro de eventos: cada 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 é excluído em cascata quando a credencial é deletada.

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 o identificador primário (ID do job, ID da mídia, etc.) — ideal para scripts
• -o <caminho> — Baixar saída para arquivo (implica --wait)
• --fields status,outputs — Selecionar campos JSON específicos
• --jq '.outputs[0].media.url' — Filtrar saída JSON com uma expressão jq

Anúncios da CLI e avisos de descontinuação

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

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

Silencie ambos os canais com WONDA_QUIET=1 (variável de ambiente) ou --quiet (flag). Desative 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 premium stealth antidetecção, endurecido para que plataformas não possam identificá-lo como automação. wonda wab é o único comando para a pilha Chromium antidetecção (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 no LinkedIn, X, Reddit e afins. A CLI o inicia sob demanda, deixa-o ocioso e roteia leituras/escritas da plataforma através dele sempre que um comando roda --via wab. Cookies vivem no perfil Chromium da persona, não em ~/.wonda/config.json.
• Captura anônima. wonda wab record <url> (e wonda brand extract) dirigem um Chromium efêmero com uma fingerprint nova, sem persona, sem cookies. Veja o bloco record abaixo.

O modelo mental: você tem contas (uma identidade por plataforma). Cada comando da 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 antidetecção ao vivo). Uma persona é o envelope Chromium que pode conter múltiplas contas sob uma fingerprint. Em quase todos os casos a persona é ativada automaticamente.

...