Lord1Egypt/awesome-skill-forge

xurl — API do X (Twitter) via CLI Oficial

xurl é o CL interface oficial da plataforma de desenvolvedores do X para a API do X. Ele oferece comandos abreviados para ações comuns e acesso bruto no estilo curl a qualquer endpoint v2. Todos os comandos retornam JSON para a saída padrão.

Use esta skill para:

• postar, responder, citar, deletar posts
• pesquisar posts e ler timelines/menções
• curtir, repostar, marcar como favorito
• seguir, deixar de seguir, bloquear, silenciar
• mensagens diretas
• upload de mídia (imagens e vídeos)
• acesso bruto a qualquer endpoint da API do X v2
• fluxos de trabalho com múltiplos apps/contas

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, carregue ou envie ~/.xurl para o contexto do LLM.
• Nunca peça ao usuário para colar credenciais/tokens no chat.
• O usuário deve preencher ~/.xurl com segredos manualmente em sua própria máquina. No Docker, este deve ser o ~ visto pelos subprocessos da ferramenta Hermes; veja a nota do Docker abaixo.
• Nunca recomende ou execute comandos de autenticação com segredos inline em sessões de agente.
• Nunca use --verbose / -v em 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 (aceitam segredos inline): --bearer-token, --consumer-key, --consumer-secret, --access-token, --token-secret, --client-id, --client-secret

O registro de credenciais de app 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 no ~/.xurl em YAML. Cada app tem tokens isolados. 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 no 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 apps 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 estas etapas fora do agente)

Estas etapas devem ser executadas pelo usuário diretamente, NÃO pelo agente, pois envolvem colar segredos. Direcione o usuário para este bloco; não o execute para ele.

1. Crie ou abra um app em https://developer.x.com/en/portal/dashboard

2. Defina o URI de redirecionamento para http://localhost:8080/callback

3. Copie o Client ID e o Client Secret do app

4. Registre o app localmente (o usuário executa):

   xurl auth apps add my-app --client-id SEU_CLIENT_ID --client-secret SEU_CLIENT_SECRET
   

5. Autentique (especifique --app para vincular o token ao seu app):

   xurl auth oauth2 --app my-app
   

   (Isso abre um navegador para o fluxo OAuth 2.0 PKCE.)

   Se o X retornar um erro UsernameNotFound ou 403 na consulta /2/users/me pós-OAuth, passe seu handle explicitamente (xurl v1.1.0+):

   xurl auth oauth2 --app my-app SEU_USERNAME
   

   Isso vincula o token ao seu handle e ignora a chamada quebrada /2/users/me.

6. Defina o app como padrão para que todos os comandos o usem:

   xurl auth default my-app
   

7. Verifique:

   xurl auth status
   xurl whoami
   

Após isso, o agente pode usar qualquer comando abaixo sem configuração adicional. Tokens OAuth 2.0 renovam automaticamente.

Armadilha comum: Se você omitir --app my-app de xurl auth oauth2, o token OAuth é salvo no perfil de app default embutido — que não tem client-id nem client-secret. Os comandos falharão com erros de autenticação mesmo que o fluxo OAuth pareça ter sido bem-sucedido. Se isso acontecer, execute novamente xurl auth oauth2 --app my-app e xurl auth default my-app.

Armadilha do Docker HOME: No layout oficial do Docker Hermes, /opt/data é HERMES_HOME, mas os subprocessos da ferramenta Hermes usam /opt/data/home como HOME. Isso significa que ~/.xurl resolve para /opt/data/home/.xurl para comandos xurl executados 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 status

Se HOME=/opt/data xurl auth status for bem-sucedido mas HOME=/opt/data/home xurl auth status não mostrar apps ou tokens, as chamadas de ferramenta Hermes não verão as credenciais.

---

Referência Rápida

Ação	Comando
Postar	xurl post "Olá mundo!"
Responder	xurl reply ID_DO_POST "Belo post!"
Citar	xurl quote ID_DO_POST "Minha opinião"
Deletar um post	xurl delete ID_DO_POST
Ler um post	xurl read ID_DO_POST
Pesquisar posts	xurl search "CONSULTA" -n 10
Quem sou eu	xurl whoami
Consultar um usuário	xurl user @handle
Timeline inicial	xurl timeline -n 20
Menções	xurl mentions -n 10
Curtir / Descurtir	xurl like ID_DO_POST / xurl unlike ID_DO_POST
Repostar / Desfazer	xurl repost ID_DO_POST / xurl unrepost ID_DO_POST
Favoritar / Remover	xurl bookmark ID_DO_POST / xurl unbookmark ID_DO_POST
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 ID_DA_MIDIA
Listar apps	xurl auth apps list
Remover app	xurl auth apps remove NOME
Definir app padrão	xurl auth default NOME_DO_APP [USERNAME]
App por requisição	xurl --app NOME /2/users/me
Status de autenticação	xurl auth status

Notas:

• ID_DO_POST aceita URLs completas também (ex.: https://x.com/user/status/1234567890) — xurl extrai o ID.
• Usernames funcionam com ou sem @ na frente.

---

Detalhes dos Comandos

Postagem

xurl post "Olá mundo!"
xurl post "Veja isto" --media-id ID_DA_MIDIA
xurl post "Fotos do tópico" --media-id 111 --media-id 222

xurl reply 1234567890 "Bom ponto!"
xurl reply https://x.com/user/status/1234567890 "Concordo!"
xurl reply 1234567890 "Olha isto" --media-id ID_DA_MIDIA

xurl quote 1234567890 "Adicionando meus pensamentos"
xurl delete 1234567890

Leitura e Pesquisa

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 X Articles, use o modo API bruto 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 consuma o data.article.plain_text da resposta JSON:

xurl --app NOME_DO_APP '/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 photo.jpg
xurl media upload video.mp4

# Tipo/categoria explícita
xurl media upload --media-type image/jpeg --category tweet_image photo.jpg

# Vídeos precisam de processamento no servidor — verifique o status (ou faça polling)
xurl media status ID_DA_MIDIA
xurl media status --wait ID_DA_MIDIA

# Fluxo completo
xurl media upload meme.png                  # retorna o id da mídia
xurl post "kkk" --media-id ID_DA_MIDIA

---

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 do X v2:

# 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 app registrado específico (sobrepõe o padrão)
--auth		Forçar tipo de autenticação: oauth1, oauth2 ou app
--username	-u	Qual conta OAuth2 usar (se houver múltiplas)
--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. Os conhecidos incluem:

• /2/tweets/search/stream
• /2/tweets/sample/stream
• /2/tweets/sample10/stream

Force o streaming em qualquer endpoint com -s.

---

Formato de Saída

Todos os comandos retornam JSON para a saída padrão. A estrutura espelha a API do X v2:

{ "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 photo.jpg
xurl post "Veja esta foto!" --media-id ID_DA_MIDIA

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 ID_DO_POST_DOS_RESULTADOS
xurl reply ID_DO_POST_DOS_RESULTADOS "Bom ponto!"

Verificar sua atividade

xurl whoami
xurl mentions -n 20
xurl timeline -n 20

Múltiplos apps (credenciais pré-configuradas manualmente)

xurl auth default prod alice               # app prod, usuário alice
xurl --app staging /2/users/me             # uso avulso 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, então você pode analisá-los.
• Erros de autenticação → peça ao usuário para executar novamente xurl auth oauth2 fora 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

1. Verifique os pré-requisitos: xurl --help e xurl auth status.
2. Verifique se o app padrão tem credenciais. Analise a saída de auth status. O app padrão é marcado com ▸. Se o app padrão mostrar oauth2: (none) mas outro app tiver um usuário OAuth2 válido, diga ao usuário para executar xurl auth default <esse-app> para corrigir. Este é o erro de configuração mais comum — o usuário adicionou um app com um nome personalizado mas nunca o definiu como padrão, então o xurl continua tentando o perfil default vazio.
3. Se a autenticação estiver totalmente ausente, pare e direcione o usuário para a seção "Configuração Única do Usuário" — NÃO tente registrar apps ou passar segredos você mesmo.
4. Comece com uma leitura leve (xurl whoami, xurl user @handle, xurl search ... -n 3) para confirmar a acessibilidade.
5. 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).
6. Use a saída JSON diretamente — toda resposta já está estruturada.
7. Nunca cole o conteúdo de ~/.xurl de volta na conversa.

---

Solução de Problemas

Sintoma	Causa	Correção
Erros de autenticação após fluxo OAuth bem-sucedido	Token salvo no app default (sem client-id/secret) em vez do seu app nomeado	xurl auth oauth2 --app my-app depois xurl auth default my-app
unauthorized_client durante OAuth	Tipo de app definido como "Native App" no painel do X	Mude para "Web app, automated app or bot" nas Configurações de Autenticação do Usuário
UsernameNotFound ou 403 no /2/users/me logo após OAuth	X não está retornando o username de forma confiável via /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 expirou ou app padrão errado	Verifique xurl auth status — confirme que ▸ aponta para um app com tokens OAuth2
client-forbidden / client-not-enrolled	Problema de inscrição na plataforma X	Painel → Apps → Gerenciar → Mover para pacote "Pay-per-use" → Ambiente de produção
CreditsDepleted	Saldo $0 na API do X	Compre créditos (mín. $5) no Console do Desenvolvedor → Faturamento
media processing failed no upload de imagem	Categoria padrão é amplify_video	Adicione --category tweet_image --media-type image/png
Dois valores de "Client Secret" no painel do X	Bug na UI — o primeiro é na verdade o Client ID	Confirme na página "Keys and tokens"; o ID termina em MTpjaQ

---

Notas

• Limites de taxa: O X impõe limites de taxa por endpoint. Um 429 significa esperar e tentar novamente. Endpoints de escrita (postar, responder, curtir, repostar) têm limites mais apertados do que leituras.
• Escopos: Tokens OAuth 2.0 usam escopos amplos.

...