xurl — API do X (Twitter) via CLI Oficial
xurl é o CLI oficial da plataforma de desenvolvedores do X para a API do X. Ele suporta comandos abreviados para ações comuns E acesso bruto no estilo curl a qualquer endpoint v2. Todos os comandos retornam JSON na saída padrão.
Use esta skill para:
- postar, responder, citar, deletar posts
- pesquisar posts brutos (JSON real de posts com IDs que você pode interagir) e ler timelines/menções
- curtir, repostar, favoritar
- seguir, deixar de seguir, bloquear, silenciar
- mensagens diretas
- upload de mídia (imagens e vídeo)
- acesso bruto a qualquer endpoint da API v2 do X
- fluxos de trabalho multi-aplicativo / multi-conta
Esta skill substitui a skill xitter mais antiga (que usava um CLI Python de terceiros). xurl é mantido pela equipe da plataforma de desenvolvedores do X, suporta OAuth 2.0 PKCE com renovação automática e cobre uma superfície de API substancialmente maior.
Segurança de Segredos (OBRIGATÓRIO)
Regras críticas ao operar dentro de uma sessão de agente/LLM:
- Nunca leia, imprima, analise, resuma, faça upload ou envie
~/.xurlpara o contexto do LLM. - Nunca peça ao usuário para colar credenciais/tokens no chat.
- O usuário deve preencher
~/.xurlcom segredos manualmente em sua própria máquina. No Docker, este deve ser o~visto pelos subprocessos da ferramenta Hermes; veja a nota sobre Docker abaixo. - Nunca recomende ou execute comandos de autenticação com segredos inline em sessões de agente.
- Nunca use
--verbose/-vem sessões de agente — pode expor cabeçalhos/tokens de autenticação. - Para verificar se as credenciais existem, use apenas:
xurl auth status.
Flags proibidas em comandos de agente (elas aceitam segredos inline):
--bearer-token, --consumer-key, --consumer-secret, --access-token, --token-secret, --client-id, --client-secret
O registro de credenciais de aplicativo e a rotação de credenciais devem ser feitos pelo usuário manualmente, fora da sessão do agente. Após o registro das credenciais, o usuário autentica com xurl auth oauth2 — também fora da sessão do agente. Os tokens persistem em ~/.xurl em YAML. Cada aplicativo tem tokens isolados. Os tokens OAuth 2.0 renovam automaticamente.
Instalação
Escolha UM método. No Linux, o script shell ou go install são os mais fáceis.
# Script shell (instala em ~/.local/bin, sem sudo, funciona em Linux + macOS)
curl -fsSL https://raw.githubusercontent.com/xdevplatform/xurl/main/install.sh | bash
# Homebrew (macOS)
brew install --cask xdevplatform/tap/xurl
# npm
npm install -g @xdevplatform/xurl
# Go
go install github.com/xdevplatform/xurl@latest
Verifique:
xurl --help
xurl auth status
Se xurl estiver instalado, mas auth status não mostrar aplicativos ou tokens, o usuário precisa concluir a autenticação manualmente — veja a próxima seção.
Configuração Única do Usuário (o usuário executa estes passos fora do agente)
Estes passos devem ser executados pelo usuário diretamente, NÃO pelo agente, pois envolvem colar segredos. Direcione o usuário para este bloco; não o execute por ele.
-
Crie ou abra um aplicativo em https://developer.x.com/en/portal/dashboard
-
Defina o URI de redirecionamento para
http://localhost:8080/callback -
Copie o ID do Cliente e o Segredo do Cliente do aplicativo
-
Registre o aplicativo localmente (o usuário executa isto):
xurl auth apps add my-app --client-id SEU_CLIENT_ID --client-secret SEU_CLIENT_SECRET -
Autentique (especifique
--apppara vincular o token ao seu aplicativo):xurl auth oauth2 --app my-app(Isso abre um navegador para o fluxo OAuth 2.0 PKCE.)
Se o X retornar um erro
UsernameNotFoundou 403 na consulta/2/users/mepós-OAuth, passe seu handle explicitamente (xurl v1.1.0+):xurl auth oauth2 --app my-app SEU_USERNAMEIsso vincula o token ao seu handle e pula a chamada
/2/users/mequebrada. -
Defina o aplicativo como padrão para que todos os comandos o usem:
xurl auth default my-app -
Verifique:
xurl auth status xurl whoami
Depois disso, o agente pode usar qualquer comando abaixo sem configuração adicional. Os tokens OAuth 2.0 renovam automaticamente.
Armadilha comum: Se você omitir
--app my-appdexurl auth oauth2, o token OAuth é salvo no perfil de aplicativodefaultembutido — que não tem client-id ou client-secret. Os comandos falharão com erros de autenticação mesmo que o fluxo OAuth pareça ter sido bem-sucedido. Se você encontrar isso, execute novamentexurl auth oauth2 --app my-appexurl auth default my-app.
Armadilha do HOME no Docker: No layout oficial do Docker Hermes,
/opt/dataéHERMES_HOME, mas os subprocessos da ferramenta Hermes usam/opt/data/homecomoHOME. Isso significa que~/.xurlresolve para/opt/data/home/.xurlpara comandosxurlexecutados pelo Hermes, não/opt/data/.xurl. Execute a configuração do usuário com o mesmo HOME:HOME=/opt/data/home xurl auth apps add my-app --client-id SEU_CLIENT_ID --client-secret SEU_CLIENT_SECRET HOME=/opt/data/home xurl auth oauth2 --app my-app SEU_USERNAME HOME=/opt/data/home xurl auth default my-app SEU_USERNAME HOME=/opt/data/home xurl auth statusSe
HOME=/opt/data xurl auth statusfor bem-sucedido, masHOME=/opt/data/home xurl auth statusnão mostrar aplicativos ou tokens, as chamadas de ferramenta do Hermes não verão as credenciais.
Referência Rápida
| Ação | Comando |
|---|---|
| Postar | xurl post "Olá mundo!" |
| Responder | xurl reply POST_ID "Belo post!" |
| Citar | xurl quote POST_ID "Minha opinião" |
| Deletar um post | xurl delete POST_ID |
| Ler um post | xurl read POST_ID |
| Pesquisar posts | xurl search "QUERY" -n 10 |
| Quem sou eu | xurl whoami |
| Buscar um usuário | xurl user @handle |
| Timeline inicial | xurl timeline -n 20 |
| Menções | xurl mentions -n 10 |
| Curtir / Descurtir | xurl like POST_ID / xurl unlike POST_ID |
| Repostar / Desfazer | xurl repost POST_ID / xurl unrepost POST_ID |
| Favoritar / Remover | xurl bookmark POST_ID / xurl unbookmark POST_ID |
| Listar favoritos / curtidas | xurl bookmarks -n 10 / xurl likes -n 10 |
| Seguir / Deixar de seguir | xurl follow @handle / xurl unfollow @handle |
| Seguindo / Seguidores | xurl following -n 20 / xurl followers -n 20 |
| Bloquear / Desbloquear | xurl block @handle / xurl unblock @handle |
| Silenciar / Dessilenciar | xurl mute @handle / xurl unmute @handle |
| Enviar DM | xurl dm @handle "mensagem" |
| Listar DMs | xurl dms -n 10 |
| Upload de mídia | xurl media upload caminho/para/arquivo.mp4 |
| Status da mídia | xurl media status MEDIA_ID |
| Listar aplicativos | xurl auth apps list |
| Remover aplicativo | xurl auth apps remove NOME |
| Definir aplicativo padrão | xurl auth default APP_NAME [USERNAME] |
| Aplicativo por requisição | xurl --app NAME /2/users/me |
| Status de autenticação | xurl auth status |
Notas:
POST_IDtambém aceita URLs completas (ex.:https://x.com/user/status/1234567890) — oxurlextrai o ID.- Nomes de usuário funcionam com ou sem
@no início.
Detalhes dos Comandos
Postagem
xurl post "Olá mundo!"
xurl post "Veja isto" --media-id MEDIA_ID
xurl post "Fotos da thread" --media-id 111 --media-id 222
xurl reply 1234567890 "Ótimo ponto!"
xurl reply https://x.com/user/status/1234567890 "Concordo!"
xurl reply 1234567890 "Olhe isto" --media-id MEDIA_ID
xurl quote 1234567890 "Adicionando meus pensamentos"
xurl delete 1234567890
Leitura e Pesquisa
xurl search consulta o índice do X como sua conta autenticada e retorna objetos de post brutos — IDs, autores, texto completo — para que os resultados possam ser imediatamente interagidos (responder, curtir, repostar, citar). Use-o quando você precisar dos posts reais em vez de uma resposta resumida sobre um tópico.
xurl read 1234567890
xurl read https://x.com/user/status/1234567890
xurl search "golang"
xurl search "from:elonmusk" -n 20
xurl search "#buildinpublic lang:en" -n 15
Para Artigos X, use o modo de API bruta em vez do atalho read. xurl read
espera um ID de post ou URL de post; não coloque read antes de um endpoint
/2/tweets/.... Solicite o campo de tweet article e ingira data.article.plain_text
da resposta JSON:
xurl --app APP_NAME '/2/tweets/2057909493250539891?expansions=author_id,attachments.media_keys,referenced_tweets.id&tweet.fields=created_at,lang,public_metrics,context_annotations,entities,possibly_sensitive,conversation_id,in_reply_to_user_id,referenced_tweets,article'
Usuários, Timeline, Menções
xurl whoami
xurl user elonmusk
xurl user @XDevelopers
xurl timeline -n 25
xurl mentions -n 20
Engajamento
xurl like 1234567890
xurl unlike 1234567890
xurl repost 1234567890
xurl unrepost 1234567890
xurl bookmark 1234567890
xurl unbookmark 1234567890
xurl bookmarks -n 20
xurl likes -n 20
Grafo Social
xurl follow @XDevelopers
xurl unfollow @XDevelopers
xurl following -n 50
xurl followers -n 50
# Grafo de outro usuário
xurl following --of elonmusk -n 20
xurl followers --of elonmusk -n 20
xurl block @spammer
xurl unblock @spammer
xurl mute @annoying
xurl unmute @annoying
Mensagens Diretas
xurl dm @someuser "Ei, vi seu post!"
xurl dms -n 25
Upload de Mídia
# Detecção automática de tipo
xurl media upload foto.jpg
xurl media upload video.mp4
# Tipo/categoria explícita
xurl media upload --media-type image/jpeg --category tweet_image foto.jpg
# Vídeos precisam de processamento no servidor — verifique o status (ou faça polling)
xurl media status MEDIA_ID
xurl media status --wait MEDIA_ID
# Fluxo de trabalho completo
xurl media upload meme.png # retorna o id da mídia
xurl post "kkk" --media-id MEDIA_ID
Acesso Bruto à API
Os atalhos cobrem operações comuns. Para qualquer outra coisa, use o modo bruto no estilo curl contra qualquer endpoint da API v2 do X:
# GET
xurl /2/users/me
# POST com corpo JSON
xurl -X POST /2/tweets -d '{"text":"Olá mundo!"}'
# DELETE / PUT / PATCH
xurl -X DELETE /2/tweets/1234567890
# Cabeçalhos personalizados
xurl -H "Content-Type: application/json" /2/some/endpoint
# Forçar streaming
xurl -s /2/tweets/search/stream
# URLs completas também funcionam
xurl https://api.x.com/2/users/me
Flags Globais
| Flag | Curta | Descrição |
|---|---|---|
--app | Usar um aplicativo registrado específico (substitui o padrão) | |
--auth | Forçar tipo de autenticação: oauth1, oauth2, ou app | |
--username | -u | Qual conta OAuth2 usar (se houver várias) |
--verbose | -v | Proibido em sessões de agente — vaza cabeçalhos de autenticação |
--trace | -t | Adicionar cabeçalho de rastreio X-B3-Flags: 1 |
Streaming
Endpoints de streaming são detectados automaticamente. Conhecidos incluem:
/2/tweets/search/stream/2/tweets/sample/stream/2/tweets/sample10/stream
Force streaming em qualquer endpoint com -s.
Formato de Saída
Todos os comandos retornam JSON na saída padrão. A estrutura espelha a API v2 do X:
{ "data": { "id": "1234567890", "text": "Olá mundo!" } }
Erros também são JSON:
{ "errors": [ { "message": "Não autorizado", "code": 403 } ] }
Fluxos de Trabalho Comuns
Postar com uma imagem
xurl media upload foto.jpg
xurl post "Veja esta foto!" --media-id MEDIA_ID
Responder a uma conversa
xurl read https://x.com/user/status/1234567890
xurl reply 1234567890 "Aqui estão meus pensamentos..."
Pesquisar e engajar
xurl search "tópico de interesse" -n 10
xurl like POST_ID_DOS_RESULTADOS
xurl reply POST_ID_DOS_RESULTADOS "Ótimo ponto!"
Verificar sua atividade
xurl whoami
xurl mentions -n 20
xurl timeline -n 20
Múltiplos aplicativos (credenciais pré-configuradas manualmente)
xurl auth default prod alice # aplicativo prod, usuário alice
xurl --app staging /2/users/me # uso único contra staging
Tratamento de Erros
- Código de saída diferente de zero em qualquer erro.
- Erros de API ainda são impressos como JSON na saída padrão, para que você possa analisá-los.
- Erros de autenticação → peça ao usuário para executar novamente
xurl auth oauth2fora da sessão do agente. - Comandos que precisam do ID do usuário chamador (curtir, repostar, favoritar, seguir, etc.) buscarão automaticamente via
/2/users/me. Uma falha de autenticação lá aparece como um erro de autenticação.
Fluxo de Trabalho do Agente
- Verifique os pré-requisitos:
xurl --helpexurl auth status. - Antes de usar
xurl search, verifique a intenção. Recorra a ele quando a tarefa precisar de objetos de post reais, contexto de conta autenticada, ou levar a uma ação de escrita no X — é a superfície certa quando o usuário quer posts com os quais possa interagir, não apenas um resumo de um tópico. - Verifique se o aplicativo padrão tem credenciais. Analise a saída
auth status. O aplicativo padrão é marcado com▸. Se o aplicativo padrão mostraroauth2: (none)mas outro aplicativo tiver um usuário oauth2 válido, diga ao usuário para executarxurl auth default <esse-aplicativo>para corrigir. Este é o erro de configuração mais comum — o usuário adicionou um aplicativo com um nome personalizado, mas nunca o definiu como padrão, então oxurlcontinua tentando o perfildefaultvazio. - Se a autenticação estiver completamente ausente, pare e direcione o usuário para a seção "Configuração Única do Usuário" — NÃO tente registrar aplicativos ou passar segredos você mesmo.
- Comece com uma leitura barata (
xurl whoami,xurl user @handle,xurl search ... -n 3) para confirmar a acessibilidade. - Confirme o post/usuário alvo e a intenção do usuário antes de qualquer ação de escrita (postar, responder, curtir, repostar, DM, seguir, bloquear, deletar).
- Apenas a saída do comando
xurl(ou a resposta bruta da API do X) prova que uma ação de alteração de estado no X aconteceu. Nunca reporte uma escrita como concluída com base em qualquer outra fonte — resultados de pesquisa, resumos ou contexto anterior. - Use a saída JSON diretamente — toda resposta já está estruturada.
- Nunca cole o conteúdo de
~/.xurlde volta na conversa.
Solução de Problemas
| Sintoma | Causa | Correção |
|---|---|---|
| Erros de autenticação após fluxo OAuth bem-sucedido | Token salvo no aplicativo default (sem client-id/secret) em vez do seu aplicativo nomeado | xurl auth oauth2 --app my-app então xurl auth default my-app |
unauthorized_client durante o OAuth | Tipo de aplicativo definido como "Aplicativo Nativo" no painel do X | Mude para "Aplicativo web, aplicativo automatizado ou bot" nas Configurações de Autenticação do Usuário |
UsernameNotFound ou 403 em /2/users/me logo após o OAuth | X não retornando nome de usuário confiavelmente de /2/users/me | Execute novamente xurl auth oauth2 --app my-app SEU_USERNAME (xurl v1.1.0+) para passar o handle explicitamente |
| 401 em toda requisição | Token expirado ou aplicativo padrão errado | Verifique xurl auth status — se o aplicativo padrão estiver vazio, execute xurl auth default my-app |
Comandos do agente falham, mas xurl auth status mostra credenciais | Caminho HOME incorreto no Docker (veja a nota sobre Docker acima) | Execute a configuração novamente com HOME=/opt/data/home |
Erro "app not found" ao usar --app | Nome do aplicativo não registrado ou digitado incorretamente | Liste com xurl auth apps list, tente novamente com o nome exato |