Samin12/skills

xurl — API de X (Twitter) vía la CLI oficial

xurl es la CLI oficial del equipo de la plataforma X Developer para la API de X. Ofrece comandos abreviados para acciones comunes Y acceso crudo tipo curl a cualquier endpoint v2. Todos los comandos devuelven JSON a la salida estándar.

Usa esta habilidad para:

• publicar, responder, citar, eliminar publicaciones
• buscar publicaciones en bruto (JSON real de publicaciones con IDs con los que puedes interactuar) y leer timelines/menciones
• dar "me gusta", republicar, marcar como favorito
• seguir, dejar de seguir, bloquear, silenciar
• mensajes directos
• subida de medios (imágenes y video)
• acceso crudo a cualquier endpoint v2 de la API de X
• flujos de trabajo con múltiples aplicaciones / múltiples cuentas

Esta habilidad reemplaza la anterior xitter (que envolvía una CLI Python de terceros). xurl es mantenida por el equipo de la plataforma X Developer, 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, proceses, resumas, subas o envíes ~/.xurl al contexto del LLM.
• Nunca le pidas al usuario que pegue credenciales/tokens en el chat.
• El usuario debe completar ~/.xurl con secretos manualmente en su propia máquina. En Docker, esto debe ser el ~ visto por los subprocesos de herramientas Hermes; consulta la nota de Docker más abajo.
• 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 encabezados/tokens de autenticación.
• Para verificar que existen credenciales, usa solo: 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 redirección en 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 de /2/users/me posterior a OAuth, pasa tu handle explícitamente (xurl v1.1.0+):

   xurl auth oauth2 --app mi-app TU_USUARIO
   

   Esto vincula el token a tu handle y omite la llamada rota a /2/users/me.

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.

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

Problema de HOME en Docker: En el diseño oficial de Docker Hermes, /opt/data es HERMES_HOME, pero los subprocesos de herramientas Hermes usan /opt/data/home como HOME. Eso significa que ~/.xurl se resuelve en /opt/data/home/.xurl para los comandos xurl ejecutados por Hermes, no en /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 funciona pero HOME=/opt/data/home xurl auth status no muestra aplicaciones ni tokens, las llamadas de herramientas Hermes no verán las credenciales.

---

Referencia Rápida

Acción	Comando
Publicar	xurl post "¡Hola mundo!"
Responder	xurl reply ID_POST "¡Buen post!"
Citar	xurl quote ID_POST "Mi opinión"
Eliminar publicación	xurl delete ID_POST
Leer publicación	xurl read ID_POST
Buscar publicaciones	xurl search "CONSULTA" -n 10
Quién soy	xurl whoami
Buscar usuario	xurl user @usuario
Timeline principal	xurl timeline -n 20
Menciones	xurl mentions -n 10
Dar / Quitar "Me gusta"	xurl like ID_POST / xurl unlike ID_POST
Republicar / Deshacer	xurl repost ID_POST / xurl unrepost ID_POST
Marcar / Desmarcar favorito	xurl bookmark ID_POST / xurl unbookmark ID_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 / Dejar de silenciar	xurl mute @usuario / xurl unmute @usuario
Enviar MD	xurl dm @usuario "mensaje"
Listar MDs	xurl dms -n 10
Subir medio	xurl media upload ruta/al/archivo.mp4
Estado del medio	xurl media status ID_MEDIO
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_POST también acepta URLs completas (ej. https://x.com/user/status/1234567890) — xurl extrae el ID.
• Los nombres de usuario funcionan con o sin @ inicial.

---

Detalles de Comandos

Publicación

xurl post "¡Hola mundo!"
xurl post "Mira esto" --media-id ID_MEDIO
xurl post "Fotos del hilo" --media-id 111 --media-id 222

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

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

Lectura y Búsqueda

xurl search consulta el índice de X como tu cuenta autenticada y devuelve objetos de publicación en bruto (IDs, autores, texto completo) para que puedas interactuar inmediatamente con los resultados (responder, dar like, republicar, citar). Úsalo cuando necesites las publicaciones reales en lugar de una respuesta resumida sobre un tema.

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 Artículos de X, usa el modo API crudo en lugar del acceso directo read. xurl read espera un ID de publicación o URL de publicación; no pongas read antes de un endpoint /2/tweets/.... Solicita el campo article del tweet y extrae 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

Interacciones

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 @usuario "¡Oye, vi tu publicación!"
xurl dms -n 25

Subida de Medios

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

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

# Los videos necesitan procesamiento en servidor — verifica el estado (o espera)
xurl media status ID_MEDIO
xurl media status --wait ID_MEDIO

# Flujo de trabajo completo
xurl media upload meme.png                  # devuelve id del medio
xurl post "jaja" --media-id ID_MEDIO

---

Acceso API Crudo

Los accesos directos cubren operaciones comunes. Para cualquier otra cosa, usa el modo crudo tipo curl contra cualquier endpoint v2 de la API 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

# Encabezados personalizados
xurl -H "Content-Type: application/json" /2/some/endpoint

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

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

---

Banderas Globales

Bandera	Corta	Descripción
--app		Usar 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 encabezados de autenticación
--trace	-t	Añadir encabezado de traza X-B3-Flags: 1

---

Streaming

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

• /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 la salida estándar. 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 ID_MEDIO

Responder a una conversación

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

Buscar e interactuar

xurl search "tema de interés" -n 10
xurl like ID_POST_DE_RESULTADOS
xurl reply ID_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 la API aún se imprimen como JSON en la salida estándar, para que puedas procesarlos.
• 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 muestra como un error de autenticación.

---

Flujo de Trabajo del Agente

1. Verifica los requisitos previos: xurl --help y xurl auth status.
2. Antes de usar xurl search, verifica la intención. Recurre a él cuando la tarea necesite objetos de publicación reales, contexto de cuenta autenticada, o conduzca a una acción de escritura en X — es la superficie adecuada cuando el usuario quiere publicaciones con las que pueda interactuar, no solo un resumen de un tema.
3. Comprueba que la aplicación predeterminada tenga credenciales. Procesa la salida de auth status. La aplicación predeterminada está marcada con ▸. Si la aplicación predeterminada muestra oauth2: (none) pero otra aplicación tiene un usuario oauth2 válido, dile al usuario que ejecute xurl auth default <esa-aplicación> para solucionarlo. Este es el error de configuración más común: el usuario añadió una aplicación con un nombre personalizado pero nunca la estableció como predeterminada, por lo que xurl sigue intentando usar el perfil default vacío.
4. Si falta la autenticación 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.
5. Comienza con una lectura económica (xurl whoami, xurl user @usuario, xurl search ... -n 3) para confirmar la accesibilidad.
6. Confirma la publicación/usuario objetivo y la intención del usuario antes de cualquier acción de escritura (publicar, responder, like, repost, MD, follow, block, delete).
7. Solo la salida del comando xurl (o la respuesta cruda de la API de X) demuestra que ocurrió una acción que cambia el estado en X. Nunca reportes una escritura como realizada basándote en cualquier otra fuente — resultados de búsqueda, resúmenes o contexto previo.
8. Usa la salida JSON directamente — cada respuesta ya está estructurada.
9. 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 tras 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 luego xurl auth default mi-app
unauthorized_client durante OAuth	Tipo de aplicación configurada como "Aplicación nativa" en el panel de X	Cambia a "Aplicación web, aplicación automatizada o bot" en Configuración de Autenticación de Usuario
UsernameNotFound o 403 en /2/users/me justo después de 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 handle explícitamente
401 en cada solicitud	Token caducado o aplicación predeterminada incorrecta	Comprueba xurl auth status — [continuación omitida para traducción]

---

Notas Adicionales

Imágenes y Video

• Formatos de imagen compatibles: JPEG, PNG, GIF, WEBP.
• Formatos de video compatibles: MP4, MOV (con códec H.264).
• Límites de tamaño: imágenes hasta 5 MB, video hasta 512 MB.
• El video se procesa en el servidor; usa xurl media status --wait ID_MEDIO para esperar a que esté listo.

Límites de Tasa (Rate Limits)

La mayoría de los endpoints de la API v2 de X tienen límites de tasa. xurl no gestiona la limitación automáticamente; los errores 429 Too Many Requests se devuelven como JSON. Si los encuentras, espera antes de reintentar.

Actualización de xurl

Para actualizar xurl, repite el método de instalación que usaste originalmente. El script de shell y brew manejan las actualizaciones correctamente. Para npm, ejecuta npm update -g @xdevplatform/xurl. Para go, vuelve a ejecutar go install github.com/xdevplatform/xurl@latest.