Lord1Egypt/awesome-skill-forge

xurl — API de X (Twitter) a través de la CLI oficial

xurl es la CLI oficial de la plataforma de desarrolladores de X para la API de X. Soporta comandos abreviados para acciones comunes Y acceso raw estilo curl a cualquier endpoint v2. Todos los comandos devuelven JSON a stdout.

Usa este skill para:

• publicar, responder, citar, eliminar publicaciones
• buscar publicaciones y leer timelines/menciones
• dar like, republicar, marcar como favorito
• seguir, dejar de seguir, bloquear, silenciar
• mensajes directos
• subir contenido multimedia (imágenes y video)
• acceso raw a cualquier endpoint de la API v2 de X
• flujos multi-aplicación / multi-cuenta

Este skill reemplaza el skill anterior xitter (que envolvía una CLI Python de terceros). xurl es mantenido por el equipo de la plataforma de desarrolladores de X, soporta OAuth 2.0 PKCE con renovación automática y cubre una superficie de API sustancialmente mayor.

---

Seguridad de Secretos (OBLIGATORIO)

Reglas críticas al operar dentro de una sesión de agente/LLM:

• Nunca leas, imprimas, analices, resumas, subas o envíes ~/.xurl al contexto del LLM.
• Nunca pidas al usuario que pegue credenciales/tokens en el chat.
• El usuario debe llenar ~/.xurl con secretos manualmente en su propia máquina. En Docker, este debe ser el ~ visto por los subprocesos de la herramienta Hermes; consulta la nota de Docker a continuación.
• Nunca recomiendes o ejecutes comandos de autenticación con secretos en línea en sesiones de agente.
• Nunca uses --verbose / -v en sesiones de agente — puede exponer tokens/cabeceras de autenticación.
• Para verificar que existen credenciales, solo usa: xurl auth status.

Banderas prohibidas en comandos de agente (aceptan secretos en línea): --bearer-token, --consumer-key, --consumer-secret, --access-token, --token-secret, --client-id, --client-secret

El registro de credenciales de aplicación y la rotación de credenciales deben ser realizados por el usuario manualmente, fuera de la sesión del agente. Después de registrar las credenciales, el usuario se autentica con xurl auth oauth2 — también fuera de la sesión del agente. Los tokens persisten en ~/.xurl en YAML. Cada aplicación tiene tokens aislados. Los tokens OAuth 2.0 se renuevan automáticamente.

---

Instalación

Elige UN método. En Linux, el script de shell o go install son los más fáciles.

# Script de shell (instala en ~/.local/bin, sin sudo, funciona en 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

Verifica:

xurl --help
xurl auth status

Si xurl está instalado pero auth status no muestra aplicaciones ni tokens, el usuario debe completar la autenticación manualmente — consulta la siguiente sección.

---

Configuración Única del Usuario (el usuario ejecuta esto fuera del agente)

Estos pasos deben ser realizados por el usuario directamente, NO por el agente, porque implican pegar secretos. Dirige al usuario a este bloque; no lo ejecutes por él.

1. Crea o abre una aplicación en https://developer.x.com/en/portal/dashboard

2. Establece la URI de redireccionamiento a http://localhost:8080/callback

3. Copia el ID de Cliente y el Secreto de Cliente de la aplicación

4. Registra la aplicación localmente (el usuario ejecuta esto):

   xurl auth apps add mi-app --client-id TU_CLIENT_ID --client-secret TU_CLIENT_SECRET
   

5. Autentica (especifica --app para vincular el token a tu aplicación):

   xurl auth oauth2 --app mi-app
   

   (Esto abre un navegador para el flujo OAuth 2.0 PKCE.)

   Si X devuelve un error UsernameNotFound o 403 en la búsqueda /2/users/me posterior al OAuth, pasa tu identificador explícitamente (xurl v1.1.0+):

   xurl auth oauth2 --app mi-app TU_USUARIO
   

   Esto vincula el token a tu identificador y omite la llamada /2/users/me defectuosa.

6. Establece la aplicación como predeterminada para que todos los comandos la usen:

   xurl auth default mi-app
   

7. Verifica:

   xurl auth status
   xurl whoami
   

Después de esto, el agente puede usar cualquier comando a continuación sin configuración adicional. Los tokens OAuth 2.0 se renuevan automáticamente.

Error común: Si omites --app mi-app de xurl auth oauth2, el token OAuth se guarda en el perfil de aplicación default incorporado — que no tiene client-id ni client-secret. Los comandos fallarán con errores de autenticación aunque el flujo OAuth parezca exitoso. Si te encuentras con esto, vuelve a ejecutar xurl auth oauth2 --app mi-app y xurl auth default mi-app.

Error de HOME en Docker: En la disposición oficial de Hermes Docker, /opt/data es HERMES_HOME, pero los subprocesos de la herramienta Hermes usan /opt/data/home como HOME. Eso significa que ~/.xurl se resuelve a /opt/data/home/.xurl para los comandos xurl ejecutados por Hermes, no /opt/data/.xurl. Ejecuta la configuración del usuario con el mismo HOME:

HOME=/opt/data/home xurl auth apps add mi-app --client-id TU_CLIENT_ID --client-secret TU_CLIENT_SECRET
HOME=/opt/data/home xurl auth oauth2 --app mi-app TU_USUARIO
HOME=/opt/data/home xurl auth default mi-app TU_USUARIO
HOME=/opt/data/home xurl auth status

Si HOME=/opt/data xurl auth status tiene éxito pero HOME=/opt/data/home xurl auth status no muestra aplicaciones ni tokens, las llamadas de la herramienta Hermes no verán las credenciales.

---

Referencia Rápida

Acción	Comando
Publicar	xurl post "¡Hola mundo!"
Responder	xurl reply ID_DEL_POST "¡Buen post!"
Citar	xurl quote ID_DEL_POST "Mi opinión"
Eliminar un post	xurl delete ID_DEL_POST
Leer un post	xurl read ID_DEL_POST
Buscar posts	xurl search "CONSULTA" -n 10
Quién soy	xurl whoami
Buscar un usuario	xurl user @usuario
Timeline principal	xurl timeline -n 20
Menciones	xurl mentions -n 10
Like / Unlike	xurl like ID_DEL_POST / xurl unlike ID_DEL_POST
Republicar / Deshacer	xurl repost ID_DEL_POST / xurl unrepost ID_DEL_POST
Marcar / Desmarcar	xurl bookmark ID_DEL_POST / xurl unbookmark ID_DEL_POST
Listar favoritos / likes	xurl bookmarks -n 10 / xurl likes -n 10
Seguir / Dejar de seguir	xurl follow @usuario / xurl unfollow @usuario
Siguiendo / Seguidores	xurl following -n 20 / xurl followers -n 20
Bloquear / Desbloquear	xurl block @usuario / xurl unblock @usuario
Silenciar / Reactivar sonido	xurl mute @usuario / xurl unmute @usuario
Enviar MD	xurl dm @usuario "mensaje"
Listar MDs	xurl dms -n 10
Subir multimedia	xurl media upload ruta/al/archivo.mp4
Estado de multimedia	xurl media status MEDIA_ID
Listar aplicaciones	xurl auth apps list
Eliminar aplicación	xurl auth apps remove NOMBRE
Establecer app predeterminada	xurl auth default NOMBRE_APP [USUARIO]
App por solicitud	xurl --app NOMBRE /2/users/me
Estado de autenticación	xurl auth status

Notas:

• ID_DEL_POST también acepta URLs completas (ej. https://x.com/usuario/status/1234567890) — xurl extrae el ID.
• Los nombres de usuario funcionan con o sin @ al inicio.

---

Detalles de Comandos

Publicación

xurl post "¡Hola mundo!"
xurl post "Mira esto" --media-id MEDIA_ID
xurl post "Hilo de fotos" --media-id 111 --media-id 222

xurl reply 1234567890 "¡Buen punto!"
xurl reply https://x.com/usuario/status/1234567890 "¡De acuerdo!"
xurl reply 1234567890 "Mira esto" --media-id MEDIA_ID

xurl quote 1234567890 "Añadiendo mis pensamientos"
xurl delete 1234567890

Lectura y Búsqueda

xurl read 1234567890
xurl read https://x.com/usuario/status/1234567890

xurl search "golang"
xurl search "from:elonmusk" -n 20
xurl search "#buildinpublic lang:en" -n 15

Para X Articles, usa el modo API raw en lugar del acceso directo read. xurl read espera un ID de post o URL de post; no pongas read delante de un endpoint /2/tweets/.... Solicita el campo de tweet article e ingiere data.article.plain_text de la respuesta JSON:

xurl --app NOMBRE_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'

Usuarios, Timeline, Menciones

xurl whoami
xurl user elonmusk
xurl user @XDevelopers

xurl timeline -n 25
xurl mentions -n 20

Interacción

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 otro usuario
xurl following --of elonmusk -n 20
xurl followers --of elonmusk -n 20

xurl block @spammer
xurl unblock @spammer
xurl mute @molesto
xurl unmute @molesto

Mensajes Directos

xurl dm @algunusuario "¡Oye, vi tu post!"
xurl dms -n 25

Subida de Multimedia

# Detección automática de tipo
xurl media upload foto.jpg
xurl media upload video.mp4

# Tipo/categoría explícitos
xurl media upload --media-type image/jpeg --category tweet_image foto.jpg

# Los videos necesitan procesamiento del lado del servidor — verifica el estado (o haz polling)
xurl media status MEDIA_ID
xurl media status --wait MEDIA_ID

# Flujo completo
xurl media upload meme.png                  # devuelve id de media
xurl post "jajaja" --media-id MEDIA_ID

---

Acceso Raw a la API

Los accesos directos cubren operaciones comunes. Para cualquier otra cosa, usa el modo raw estilo curl contra cualquier endpoint de la API v2 de X:

# GET
xurl /2/users/me

# POST con cuerpo JSON
xurl -X POST /2/tweets -d '{"text":"¡Hola mundo!"}'

# DELETE / PUT / PATCH
xurl -X DELETE /2/tweets/1234567890

# Cabeceras personalizadas
xurl -H "Content-Type: application/json" /2/some/endpoint

# Forzar streaming
xurl -s /2/tweets/search/stream

# URLs completas también funcionan
xurl https://api.x.com/2/users/me

---

Banderas Globales

Bandera	Corta	Descripción
--app		Usa una aplicación registrada específica (anula la predeterminada)
--auth		Forzar tipo de autenticación: oauth1, oauth2, o app
--username	-u	Qué cuenta OAuth2 usar (si existen varias)
--verbose	-v	Prohibido en sesiones de agente — filtra cabeceras de autenticación
--trace	-t	Añade cabecera de traza X-B3-Flags: 1

---

Streaming

Los endpoints de streaming se detectan automáticamente. Los conocidos incluyen:

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

Fuerza streaming en cualquier endpoint con -s.

---

Formato de Salida

Todos los comandos devuelven JSON a stdout. La estructura refleja la API v2 de X:

{ "data": { "id": "1234567890", "text": "¡Hola mundo!" } }

Los errores también son JSON:

{ "errors": [ { "message": "No autorizado", "code": 403 } ] }

---

Flujos de Trabajo Comunes

Publicar con una imagen

xurl media upload foto.jpg
xurl post "¡Mira esta foto!" --media-id MEDIA_ID

Responder a una conversación

xurl read https://x.com/usuario/status/1234567890
xurl reply 1234567890 "Aquí van mis pensamientos..."

Buscar e interactuar

xurl search "tema de interés" -n 10
xurl like ID_DEL_POST_DE_RESULTADOS
xurl reply ID_DEL_POST_DE_RESULTADOS "¡Buen punto!"

Revisar tu actividad

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

Múltiples aplicaciones (credenciales preconfiguradas manualmente)

xurl auth default prod alice               # app prod, usuario alice
xurl --app staging /2/users/me             # uso único contra staging

---

Manejo de Errores

• Código de salida distinto de cero en cualquier error.
• Los errores de API aún se imprimen como JSON a stdout, por lo que puedes analizarlos.
• Errores de autenticación → haz que el usuario vuelva a ejecutar xurl auth oauth2 fuera de la sesión del agente.
• Los comandos que necesitan el ID de usuario del llamante (like, repost, bookmark, follow, etc.) lo obtendrán automáticamente mediante /2/users/me. Un fallo de autenticación allí se manifiesta como un error de autenticación.

---

Flujo de Trabajo del Agente

1. Verifica los prerrequisitos: xurl --help y xurl auth status.
2. Comprueba que la app predeterminada tenga credenciales. Analiza la salida de auth status. La app predeterminada está marcada con ▸. Si la app predeterminada muestra oauth2: (none) pero otra app tiene un usuario oauth2 válido, dile al usuario que ejecute xurl auth default <esa-app> para solucionarlo. Este es el error de configuración más común — el usuario añadió una app con un nombre personalizado pero nunca la estableció como predeterminada, por lo que xurl sigue intentando usar el perfil vacío default.
3. Si la autenticación falta por completo, detente y dirige al usuario a la sección "Configuración Única del Usuario" — NO intentes registrar aplicaciones ni pasar secretos tú mismo.
4. Comienza con una lectura barata (xurl whoami, xurl user @usuario, xurl search ... -n 3) para confirmar la accesibilidad.
5. Confirma el post/usuario objetivo y la intención del usuario antes de cualquier acción de escritura (post, reply, like, repost, DM, follow, block, delete).
6. Usa la salida JSON directamente — cada respuesta ya está estructurada.
7. Nunca pegues el contenido de ~/.xurl de vuelta en la conversación.

---

Solución de Problemas

Síntoma	Causa	Solución
Errores de autenticación después de un flujo OAuth exitoso	Token guardado en la app default (sin client-id/secret) en lugar de tu app nombrada	xurl auth oauth2 --app mi-app y luego xurl auth default mi-app
unauthorized_client durante OAuth	Tipo de app configurado como "Native App" en el panel de X	Cambia a "Web app, automated app or bot" en Configuración de Autenticación de Usuario
UsernameNotFound o 403 en /2/users/me justo después del OAuth	X no devuelve el nombre de usuario de forma fiable desde /2/users/me	Vuelve a ejecutar xurl auth oauth2 --app mi-app TU_USUARIO (xurl v1.1.0+) para pasar el identificador explícitamente
401 en cada solicitud	Token caducado o app predeterminada incorrecta	Verifica xurl auth status — confirma que ▸ apunta a una app con tokens oauth2
client-forbidden / client-not-enrolled	Problema de suscripción en la plataforma X	Panel → Apps → Gestionar → Mover al paquete "Pay-per-use" → Entorno de producción
CreditsDepleted	Saldo $0 en la API de X	Compra créditos (mín. $5) en Consola de Desarrollador → Facturación
media processing failed en subida de imagen	La categoría predeterminada es amplify_video	Añade --category tweet_image --media-type image/png
Dos valores de "Client Secret" en el panel de X	Error de interfaz de usuario — el primero es en realidad el Client ID	Confirma en la página "Keys and tokens"; el ID termina en MTpjaQ

---

Notas

• Límites de tasa: X impone límites de tasa por endpoint. Un 429 significa esperar y reintentar. Los endpoints de escritura (post, reply, like, repost) tienen límites más estrictos que los de lectura.
• Ámbitos (Scopes): Los tokens OAuth 2.0 usan ámbitos amplios que cubren lectura/escritura/DM/offline. La configuración del agente no debe requerir ámbitos más específicos.
• Tokens sin app: El perfil de app default incorporado no tiene client-id ni client-secret, por lo que solo puede usar OAuth 1.0 o Bearer Token. Las apps registradas con credenciales pueden usar OAuth 2.0 con renovación automática o OAuth 1.0.
• Versión de la API: xurl solo apunta a la API v2 de X ("X API v2"). Los endpoints v1.1 no son compatibles. Casi todas las funciones modernas de X están disponibles en v2, pero algunas API heredadas (transmisión de anuncios, analytics v1.1) pueden no funcionar.