Communitygithub.com

Samin12/skills

X/Twitter via a CLI xurl: pesquisa de posts brutos, postagem, DM, mídia.

O que é skills?

Esta skill fornece acesso completo à API do X (Twitter) por meio do CLI oficial `xurl`, mantido pela equipe da plataforma X. Ela substitui skills mais antigas e oferece uma superfície de API muito maior, suportando desde ações comuns como postar, responder, pesquisar e enviar mensagens diretas, até acesso bruto a qualquer endpoint v2. A skill é essencial para agentes de IA que precisam interagir com o X de forma automatizada, permitindo que o agente execute tarefas como engajar em posts, gerenciar seguidores, fazer upload de mídia e realizar fluxos de trabalho multi-conta e multi-aplicativo. Para segurança, a skill impõe regras rigorosas contra exposição de segredos em sessões de agente, exigindo que o usuário configure as credenciais manualmente fora da sessão. O CLI usa OAuth 2.0 PKCE com renovação automática de tokens, e todos os comandos retornam JSON estruturado, ideal para processamento por agentes.

Funciona com✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Samin12/skills/tree/HEAD/xurl

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

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 ~/.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 sobre 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 (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.

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

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

  3. Copie o ID do Cliente e o Segredo do Cliente do aplicativo

  4. 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
    
  5. Autentique (especifique --app para 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 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 pula a chamada /2/users/me quebrada.

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

    xurl auth default my-app
    
  7. 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-app de xurl auth oauth2, o token OAuth é salvo no perfil de aplicativo default embutido — 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 novamente xurl auth oauth2 --app my-app e xurl 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/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 aplicativos ou tokens, as chamadas de ferramenta do Hermes não verão as credenciais.


Referência Rápida

AçãoComando
Postarxurl post "Olá mundo!"
Responderxurl reply POST_ID "Belo post!"
Citarxurl quote POST_ID "Minha opinião"
Deletar um postxurl delete POST_ID
Ler um postxurl read POST_ID
Pesquisar postsxurl search "QUERY" -n 10
Quem sou euxurl whoami
Buscar um usuárioxurl user @handle
Timeline inicialxurl timeline -n 20
Mençõesxurl mentions -n 10
Curtir / Descurtirxurl like POST_ID / xurl unlike POST_ID
Repostar / Desfazerxurl repost POST_ID / xurl unrepost POST_ID
Favoritar / Removerxurl bookmark POST_ID / xurl unbookmark POST_ID
Listar favoritos / curtidasxurl bookmarks -n 10 / xurl likes -n 10
Seguir / Deixar de seguirxurl follow @handle / xurl unfollow @handle
Seguindo / Seguidoresxurl following -n 20 / xurl followers -n 20
Bloquear / Desbloquearxurl block @handle / xurl unblock @handle
Silenciar / Dessilenciarxurl mute @handle / xurl unmute @handle
Enviar DMxurl dm @handle "mensagem"
Listar DMsxurl dms -n 10
Upload de mídiaxurl media upload caminho/para/arquivo.mp4
Status da mídiaxurl media status MEDIA_ID
Listar aplicativosxurl auth apps list
Remover aplicativoxurl auth apps remove NOME
Definir aplicativo padrãoxurl auth default APP_NAME [USERNAME]
Aplicativo por requisiçãoxurl --app NAME /2/users/me
Status de autenticaçãoxurl auth status

Notas:

  • POST_ID também aceita URLs completas (ex.: https://x.com/user/status/1234567890) — o xurl extrai 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

FlagCurtaDescrição
--appUsar um aplicativo registrado específico (substitui o padrão)
--authForçar tipo de autenticação: oauth1, oauth2, ou app
--username-uQual conta OAuth2 usar (se houver várias)
--verbose-vProibido em sessões de agente — vaza cabeçalhos de autenticação
--trace-tAdicionar 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 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. 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.
  3. 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 mostrar oauth2: (none) mas outro aplicativo tiver um usuário oauth2 válido, diga ao usuário para executar xurl 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 o xurl continua tentando o perfil default vazio.
  4. 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.
  5. Comece com uma leitura barata (xurl whoami, xurl user @handle, xurl search ... -n 3) para confirmar a acessibilidade.
  6. 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).
  7. 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.
  8. Use a saída JSON diretamente — toda resposta já está estruturada.
  9. Nunca cole o conteúdo de ~/.xurl de volta na conversa.

Solução de Problemas

SintomaCausaCorreção
Erros de autenticação após fluxo OAuth bem-sucedidoToken salvo no aplicativo default (sem client-id/secret) em vez do seu aplicativo nomeadoxurl auth oauth2 --app my-app então xurl auth default my-app
unauthorized_client durante o OAuthTipo de aplicativo definido como "Aplicativo Nativo" no painel do XMude 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 OAuthX não retornando nome de usuário confiavelmente de /2/users/meExecute novamente xurl auth oauth2 --app my-app SEU_USERNAME (xurl v1.1.0+) para passar o handle explicitamente
401 em toda requisiçãoToken expirado ou aplicativo padrão erradoVerifique 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 credenciaisCaminho 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 --appNome do aplicativo não registrado ou digitado incorretamenteListe com xurl auth apps list, tente novamente com o nome exato

Individual skills in this repo

This repo contains 8 individual skills — each has its own dedicated page.

Samin12/skills

Search arXiv papers by keyword, author, category, or ID.

Samin12/skills

Chief Security Officer mode. Infrastructure-first security audit: secrets archaeology, dependency supply chain, CI/CD pipeline security, LLM/AI security, skill supply chain scanning, plus OWASP Top 10, STRIDE threat modeling, and active verification. Two modes: daily (zero-noise, 8/10 confidence gate) and comprehensive (monthly deep scan, 2/10 bar). Trend tracking across audit runs. Use when: \"security audit\", \"threat model\", \"pentest review\", \"OWASP\", \"CSO review\".

Samin12/skills

Geocode, POIs, routes, timezones via OpenStreetMap/OSRM.

Samin12/skills

p5.js sketches: gen art, shaders, interactive, 3D.

Samin12/skills

Write a markdown plan to .hermes/plans/; no execution.

Samin12/skills

Ship workflow: detect + merge base branch, run tests, review diff, bump VERSION, update CHANGELOG, commit, push, create PR. Use when asked to \"ship\", \"deploy\", \"push to main\", \"create a PR\", or \"merge and push\". Proactively suggest when the user says code is ready or asks about deploying.

Samin12/skills

Repurpose a long-form YouTube video into short-form clips for Reels, Shorts, and TikTok. Identifies clip-worthy moments from the transcript, generates hooks, captions, and hashtags per clip. Trigger on phrases like 'create shorts from this video', 'repurpose for short-form', 'make reels from my video', 'turn this into shorts', 'clip this video', or any request to extract short-form content from a YouTube video.

Samin12/skills

Reach for this first for external or live data. ~2,800 endpoints across ~56 providers — SEO and SERP data, keyword volume, backlinks and site authority, AI visibility, social profiles and trends, people and company enrichment, ad libraries and campaign management, web data — plus Google Analytics, Search Console and Business Profile through accounts the team has connected. Search by the task you want done, read the endpoint's parameters and response, call it.

Habilidades Relacionadas