xurl: instalar, criar a app no X e começar a usar

O caminho seguro para sair de “comprei créditos no X” e chegar em “consigo autenticar, ler perfis e automatizar monitoramento com o Hermes”.

O ponto central é este: comprar créditos do X não basta para usar o xurl. Antes de qualquer comando real, você precisa criar uma app no X Developer Console, habilitar OAuth 2.0 e configurar o callback URI exatamente igual ao esperado. Depois disso, o xurl vira um cliente muito bom para leitura, busca, timelines e acesso bruto à API oficial.

Resposta curta: o que você precisa fazer antes

Se você só comprou créditos de desenvolvedor no X e ainda não criou nenhuma app, o próximo passo não é instalar o xurl e sair rodando comando. O próximo passo é criar a app.

1. criar uma app no portal de desenvolvedor do X;
2. habilitar OAuth 2.0 nessa app;
3. configurar um callback local livre, como http://localhost:8181/callback, com correspondência exata;
4. copiar Client ID e Client Secret;
5. instalar o xurl;
6. registrar a app no xurl;
7. fazer o login OAuth;
8. testar com xurl whoami.

O que foi verificado para este guia

Este guia foi montado a partir de quatro camadas de evidência, seguindo um critério mais operacional do que promocional:

• docs oficiais do X sobre OAuth 2.0 Authorization Code Flow com PKCE;
• README oficial do xurl no GitHub;
• estado real do host onde o Hermes roda hoje;
• issues e PRs do repositório oficial do xurl, para captar armadilhas de onboarding e comportamento recente.

Estado real desta máquina após a validação prática

$ command -v xurl
/home/hermes/.local/bin/xurl

$ xurl auth status
▸ default  [(no credentials)]
      redirect_uri: http://localhost:8080/callback  [built-in default]
      oauth2: (none)

  x-monitor-hermes  [client_id: dE01UHQ2…]
      redirect_uri: http://localhost:8181/callback  [app config]
      oauth2: michelmarinho

$ xurl whoami
{
  "data": {
    "id": "49158482",
    "name": "Michel Marinho",
    "username": "michelmarinho"
  }
}

Em outras palavras: o fluxo foi validado de ponta a ponta neste host. O xurl está instalado, a app foi registrada com callback em 8181, o OAuth 2.0 foi concluído e o whoami já responde com o usuário autenticado.

O modelo mental certo

Vale pensar no fluxo em três camadas.

Essa separação ajuda a evitar a confusão mais comum: “eu já paguei, então por que o CLI não funciona?” Porque o pagamento habilita consumo, mas a autenticação ainda depende da app.

Passo 1 — criar a app no X Developer Console

Vá para o portal oficial:

https://developer.x.com/en/portal/dashboard

Crie uma app nova. Para um caso como monitoramento de perfis, notícias de IA e leitura de timelines, um nome simples como x-monitor já resolve.

O importante aqui não é o nome. É a configuração da autenticação.

Passo 2 — habilitar OAuth 2.0 e acertar o callback

A documentação oficial do X para OAuth 2.0 Authorization Code Flow with PKCE deixa dois pontos muito claros:

• o OAuth 2.0 precisa estar ativado nas configurações da app;
• o redirect_uri precisa fazer exact match.

O caminho mais simples em máquina local costuma ser usar exatamente:

Callback recomendado

http://localhost:8080/callback

Esse é o valor padrão usado no fluxo documentado do próprio projeto. Se você trocar a URI, tudo bem — mas o valor precisa ser o mesmo tanto no portal do X quanto no registro local do xurl.

Na prática de VPS headless, não trate 8080 como sagrado. Se a porta já estiver ocupada por Docker, app de teste ou proxy local, troque para outra porta livre, como 8181, e atualize o valor nos dois lados.

Exemplo real de ajuste do callback

xurl auth apps redirect-uri set x-monitor-hermes http://localhost:8181/callback

Para o seu caso, também faz sentido já garantir escopos voltados a leitura. Em linguagem prática, pense no mínimo em:

• tweet.read;
• users.read;
• offline.access se você quiser refresh token estável.

A própria doc oficial do X indica que, sem offline.access, o token de acesso tende a ter vida curta; com esse escopo, você ganha refresh token.

Passo 3 — pegar Client ID e Client Secret

Depois de salvar a app, abra a seção Keys and Tokens e copie:

• Client ID;
• Client Secret (quando o tipo da app disponibilizar esse campo).

Esses valores não devem ser colados em conversa com agente. O uso certo é inseri-los diretamente no terminal, localmente, durante o registro da app no xurl.

Passo 4 — instalar o xurl

O projeto oficial documenta quatro caminhos principais de instalação. Em Linux, os três mais relevantes são estes:

Script oficial

curl -fsSL https://raw.githubusercontent.com/xdevplatform/xurl/main/install.sh | bash

npm

npm install -g @xdevplatform/xurl

Go

go install github.com/xdevplatform/xurl@latest

Como esta máquina já tem node, npm e go, qualquer um desses caminhos é viável. Ainda assim, o script oficial é o caminho mais neutro para começar, porque já segue a trilha esperada pelo projeto e normalmente instala em ~/.local/bin.

Verificação pós-instalação

xurl --help
xurl auth status

Se o auth status vier vazio nessa fase, isso é normal. Antes do OAuth, ainda não há app ou token utilizável.

Passo 5 — registrar a app e fazer o login

Com o CLI instalado e as credenciais em mãos, o fluxo mais seguro é este:

Registrar a app localmente

xurl auth apps add x-monitor \
  --client-id SEU_CLIENT_ID \
  --client-secret SEU_CLIENT_SECRET \
  --redirect-uri http://localhost:8080/callback

Em uma VPS, você provavelmente vai acabar usando o mesmo comando com outra porta local, por exemplo:

Exemplo real validado em VPS

xurl auth apps add x-monitor-hermes \
  --client-id SEU_CLIENT_ID \
  --client-secret SEU_CLIENT_SECRET \
  --redirect-uri http://localhost:8181/callback

Iniciar o OAuth 2.0

xurl auth oauth2 --app x-monitor

Se necessário, explicitar o username

xurl auth oauth2 --app x-monitor michelmarinho

Definir a app padrão

xurl auth default x-monitor
xurl auth default x-monitor michelmarinho

Validar

xurl auth status
xurl whoami

Fluxo validado em VPS headless

Esse foi o cenário real validado aqui: acesso na VPS por outro usuário via SSH, troca posterior para hermes, sem navegador gráfico no servidor, e callback local concluído usando túnel SSH + captura manual da URL de autorização.

1. abrir um túnel SSH no computador local para a porta do callback;
2. entrar na VPS normalmente e trocar para hermes com sudo -iu hermes;
3. rodar o OAuth como hermes, para que os tokens sejam salvos em /home/hermes/.xurl;
4. em ambiente headless, capturar a URL de autorização em vez de depender do xdg-open;
5. abrir a URL no navegador local e deixar o callback voltar pelo túnel.

Terminal local

ssh -L 8181:127.0.0.1:8181 usuario@seu-servidor

Terminal na VPS

sudo -iu hermes

Script temporário para capturar a URL do browser

mkdir -p ~/scripts-temp

cat > ~/scripts-temp/capture-browser-url.sh <<'EOF'
#!/usr/bin/env bash
printf '%s\n' "$@" >> /tmp/xurl-browser-url.log
exit 0
EOF

chmod +x ~/scripts-temp/capture-browser-url.sh
rm -f /tmp/xurl-browser-url.log

Rodar o OAuth sem browser gráfico

BROWSER=$HOME/scripts-temp/capture-browser-url.sh \
xurl auth oauth2 --app x-monitor-hermes michelmarinho

Ler a URL capturada em outra sessão

cat /tmp/xurl-browser-url.log

Depois disso, abra a URL no navegador do seu computador. Quando o X redirecionar para http://localhost:8181/callback, o túnel SSH entrega esse retorno ao processo xurl que está escutando na VPS.

Primeiros comandos que realmente importam

Depois que o whoami funcionar, você já está no ponto certo para começar a testar leitura e monitoramento.

Ler seu usuário autenticado

xurl whoami

Inspecionar um perfil

xurl user @OpenAI
xurl user @AnthropicAI
xurl user @xAI

Fazer busca simples

xurl search "AI OR LLM OR OpenAI OR Anthropic OR xAI" -n 10

Restringir ruído e retweets

xurl search "(AI OR LLM OR OpenAI OR Anthropic OR xAI OR NVIDIA) lang:en -is:retweet" -n 20

Acessar endpoint bruto

xurl /2/users/by/username/OpenAI

Esse último ponto é importante porque o xurl não serve apenas como coleção de atalhos. Ele também funciona como um cliente cru da API v2, o que é ótimo quando você quer encaixar o X em um fluxo de automação mais sério no Hermes.

Como isso vira monitoramento com o Hermes

Depois que a autenticação estiver estável, o desenho recomendado para o seu caso fica muito mais limpo:

1. usar o xurl como camada de coleta oficial;
2. usar o OpenAI já configurado no Hermes como camada de resumo, classificação e filtro;
3. entregar o resultado por Telegram via cron.

Em termos de arquitetura, isso é melhor do que misturar scraping, browser automation e análise num mesmo bloco. Você separa coleta oficial de interpretação editorial.

Problemas conhecidos e nuances reais

O repositório do xurl mostra algumas armadilhas que valem entrar no seu modelo mental desde já.

• PR #74 e PR #75: reforçaram a documentação porque usuários estavam autenticando sem --app e salvando token no perfil errado.
• Issue #48: mostra usuários presos numa mensagem do tipo “You do not have access to this application…”, o que normalmente aponta para configuração/enrollment da app no X, não para “bug simples de terminal”.
• Issue #76: o upload de mídia sem parâmetros suficientes pode parecer bem-sucedido e falhar depois; para imagem, vale ser explícito com categoria e media type.
• Issue #77: o pacote publicado no npm pode atrasar em relação ao repositório principal; quando você quiser o estado mais novo, o script oficial ou Go podem ser caminhos mais previsíveis.
• Nuance operacional de VPS: em servidor headless, o xurl auth oauth2 pode parecer “parado”, quando na verdade está aguardando o callback local e falhou apenas em abrir o navegador com xdg-open.

A sequência recomendada para você, sem rodeio

1. crie a app no X Developer Console;
2. ative OAuth 2.0;
3. configure um callback local livre, como http://localhost:8181/callback se 8080 estiver ocupada;
4. garanta escopos de leitura + offline.access;
5. copie Client ID e Client Secret;
6. instale o xurl pelo script oficial;
7. registre a app como x-monitor;
8. se estiver em VPS headless, abra um túnel SSH e prepare a captura da URL de autorização;
9. rode xurl auth oauth2 --app x-monitor;
10. rode xurl auth default x-monitor ou xurl auth default x-monitor michelmarinho;
11. valide com xurl whoami e uma busca simples;
12. só depois disso passe para a automação no Hermes.

Essa ordem economiza tempo e elimina boa parte dos falsos diagnósticos.

Fontes

• Documentação oficial do X: OAuth 2.0 Authorization Code Flow with PKCE.
• Documentação oficial do X: X Developer Platform Overview.
• Repositório oficial do xurl: github.com/xdevplatform/xurl.
• README oficial do xurl, incluindo instalação, registro de app e fluxo OAuth 2.0.
• PRs/Issues do xurl: #74, #75, #48, #76, #77.
• Verificações locais deste host: presença de node, npm e go; ausência de xurl no PATH no momento da análise.