Samin12/skills

xurl — API X (Twitter) via l'interface CLI officielle

xurl est l'interface CLI officielle de la plateforme de développement X pour l'API X. Elle propose des commandes raccourcies pour les actions courantes ET un accès brut de type curl à n'importe quel point d'accès v2. Toutes les commandes renvoient du JSON sur la sortie standard.

Utilisez cette compétence pour :

• publier, répondre, citer, supprimer des posts
• rechercher des posts bruts (JSON de post réel avec des ID que vous pouvez utiliser) et lire les timelines/mentions
• liker, reposter, mettre en favori
• suivre, ne plus suivre, bloquer, masquer
• messages directs
• téléchargements de médias (images et vidéos)
• accès brut à n'importe quel point d'accès de l'API X v2
• workflows multi-applications / multi-comptes

Cette compétence remplace l'ancienne compétence xitter (qui encapsulait un CLI Python tiers). xurl est maintenue par l'équipe de la plateforme des développeurs X, prend en charge OAuth 2.0 PKCE avec renouvellement automatique et couvre une surface d'API considérablement plus large.

---

Sécurité des secrets (OBLIGATOIRE)

Règles critiques lors du fonctionnement dans une session agent/LLM :

• Ne jamais lire, afficher, analyser, résumer, télécharger ou envoyer ~/.xurl dans le contexte du LLM.
• Ne jamais demander à l'utilisateur de coller des identifiants/jetons dans le chat.
• L'utilisateur doit remplir ~/.xurl avec les secrets manuellement sur sa propre machine. Dans Docker, cela doit être le ~ vu par les sous-processus de l'outil Hermes ; voir la note Docker ci-dessous.
• Ne jamais recommander ou exécuter des commandes d'authentification avec des secrets en ligne dans les sessions d'agent.
• Ne jamais utiliser --verbose / -v dans les sessions d'agent — cela peut exposer les en-têtes/jetons d'authentification.
• Pour vérifier que les identifiants existent, utilisez uniquement : xurl auth status.

Indicateurs interdits dans les commandes d'agent (ils acceptent des secrets en ligne) : --bearer-token, --consumer-key, --consumer-secret, --access-token, --token-secret, --client-id, --client-secret

L'enregistrement des identifiants d'application et la rotation des identifiants doivent être effectués par l'utilisateur manuellement, en dehors de la session d'agent. Une fois les identifiants enregistrés, l'utilisateur s'authentifie avec xurl auth oauth2 — également en dehors de la session d'agent. Les jetons persistent dans ~/.xurl en YAML. Chaque application a des jetons isolés. Les jetons OAuth 2.0 se renouvellent automatiquement.

---

Installation

Choisissez UNE méthode. Sous Linux, le script shell ou go install sont les plus simples.

# Script shell (installe dans ~/.local/bin, sans sudo, fonctionne sous 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

Vérifiez :

xurl --help
xurl auth status

Si xurl est installé mais que auth status n'affiche aucune application ou jeton, l'utilisateur doit terminer l'authentification manuellement — voir la section suivante.

---

Configuration utilisateur unique (exécutée par l'utilisateur en dehors de l'agent)

Ces étapes doivent être effectuées par l'utilisateur directement, PAS par l'agent, car elles impliquent le collage de secrets. Dirigez l'utilisateur vers ce bloc ; ne l'exécutez pas à sa place.

1. Créez ou ouvrez une application sur https://developer.x.com/en/portal/dashboard

2. Définissez l'URI de redirection sur http://localhost:8080/callback

3. Copiez l'ID client et le secret client de l'application

4. Enregistrez l'application localement (l'utilisateur exécute) :

   xurl auth apps add my-app --client-id VOTRE_ID_CLIENT --client-secret VOTRE_SECRET_CLIENT
   

5. Authentifiez-vous (spécifiez --app pour lier le jeton à votre application) :

   xurl auth oauth2 --app my-app
   

   (Ceci ouvre un navigateur pour le flux OAuth 2.0 PKCE.)

   Si X renvoie une erreur UsernameNotFound ou 403 lors de la recherche /2/users/me post-OAuth, transmettez votre identifiant explicitement (xurl v1.1.0+) :

   xurl auth oauth2 --app my-app VOTRE_NOM_UTILISATEUR
   

   Ceci lie le jeton à votre identifiant et ignore l'appel /2/users/me défaillant.

6. Définissez l'application comme application par défaut pour que toutes les commandes l'utilisent :

   xurl auth default my-app
   

7. Vérifiez :

   xurl auth status
   xurl whoami
   

Après cela, l'agent peut utiliser n'importe quelle commande ci-dessous sans configuration supplémentaire. Les jetons OAuth 2.0 se renouvellent automatiquement.

Piège courant : Si vous omettez --app my-app de xurl auth oauth2, le jeton OAuth est enregistré dans le profil d'application default intégré — qui n'a ni client-id ni client-secret. Les commandes échoueront avec des erreurs d'authentification même si le flux OAuth a semblé réussir. Si vous rencontrez ce problème, réexécutez xurl auth oauth2 --app my-app et xurl auth default my-app.

Piège Docker HOME : Dans la disposition officielle de Docker Hermes, /opt/data est HERMES_HOME, mais les sous-processus de l'outil Hermes utilisent /opt/data/home comme HOME. Cela signifie que ~/.xurl est résolu en /opt/data/home/.xurl pour les commandes xurl exécutées par Hermes, et non en /opt/data/.xurl. Exécutez la configuration utilisateur avec le même HOME :

HOME=/opt/data/home xurl auth apps add my-app --client-id VOTRE_ID_CLIENT --client-secret VOTRE_SECRET_CLIENT
HOME=/opt/data/home xurl auth oauth2 --app my-app VOTRE_NOM_UTILISATEUR
HOME=/opt/data/home xurl auth default my-app VOTRE_NOM_UTILISATEUR
HOME=/opt/data/home xurl auth status

Si HOME=/opt/data xurl auth status réussit mais que HOME=/opt/data/home xurl auth status n'affiche aucune application ou jeton, les appels d'outils Hermes ne verront pas les identifiants.

---

Référence rapide

Action	Commande
Publier	xurl post "Bonjour le monde !"
Répondre	xurl reply ID_POST "Beau post !"
Citer	xurl quote ID_POST "Mon avis"
Supprimer un post	xurl delete ID_POST
Lire un post	xurl read ID_POST
Rechercher des posts	xurl search "REQUÊTE" -n 10
Qui suis-je	xurl whoami
Rechercher un utilisateur	xurl user @identifiant
Fil d'actualité	xurl timeline -n 20
Mentions	xurl mentions -n 10
Liker / Ne plus liker	xurl like ID_POST / xurl unlike ID_POST
Reposter / Annuler	xurl repost ID_POST / xurl unrepost ID_POST
Mettre en favori / Retirer	xurl bookmark ID_POST / xurl unbookmark ID_POST
Lister les favoris / likes	xurl bookmarks -n 10 / xurl likes -n 10
Suivre / Ne plus suivre	xurl follow @identifiant / xurl unfollow @identifiant
Abonnements / Abonnés	xurl following -n 20 / xurl followers -n 20
Bloquer / Débloquer	xurl block @identifiant / xurl unblock @identifiant
Masquer / Démasquer	xurl mute @identifiant / xurl unmute @identifiant
Envoyer un MP	xurl dm @identifiant "message"
Lister les MP	xurl dms -n 10
Télécharger un média	xurl media upload chemin/vers/fichier.mp4
Statut du média	xurl media status ID_MÉDIA
Lister les applications	xurl auth apps list
Supprimer une application	xurl auth apps remove NOM
Définir l'application par défaut	xurl auth default NOM_APP [NOM_UTILISATEUR]
Application par requête	xurl --app NOM /2/users/me
Statut d'authentification	xurl auth status

Notes :

• ID_POST accepte également les URL complètes (par exemple https://x.com/user/status/1234567890) — xurl extrait l'ID.
• Les noms d'utilisateur fonctionnent avec ou sans @ préfixé.

---

Détails des commandes

Publication

xurl post "Bonjour le monde !"
xurl post "Regardez ça" --media-id ID_MÉDIA
xurl post "Images du fil" --media-id 111 --media-id 222

xurl reply 1234567890 "Excellente remarque !"
xurl reply https://x.com/user/status/1234567890 "D'accord !"
xurl reply 1234567890 "Regardez ça" --media-id ID_MÉDIA

xurl quote 1234567890 "J'ajoute mes réflexions"
xurl delete 1234567890

Lecture et recherche

xurl search interroge l'index X en tant que votre compte authentifié et renvoie des objets de post bruts — ID, auteurs, texte intégral — afin que les résultats puissent être immédiatement utilisés (répondre, liker, reposter, citer). Utilisez-le lorsque vous avez besoin des posts réels plutôt que d'une réponse résumée sur un sujet.

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

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

Pour les Articles X, utilisez plutôt le mode API brut que le raccourci read. xurl read s'attend à un ID de post ou une URL de post ; ne mettez pas read devant un point d'accès /2/tweets/.... Demandez le champ de tweet article et ingérez data.article.plain_text de la réponse JSON :

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

Utilisateurs, fil d'actualité, mentions

xurl whoami
xurl user elonmusk
xurl user @XDevelopers

xurl timeline -n 25
xurl mentions -n 20

Engagement

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

Graphe social

xurl follow @XDevelopers
xurl unfollow @XDevelopers

xurl following -n 50
xurl followers -n 50

# Graphe d'un autre utilisateur
xurl following --of elonmusk -n 20
xurl followers --of elonmusk -n 20

xurl block @spammer
xurl unblock @spammer
xurl mute @agacant
xurl unmute @agacant

Messages directs

xurl dm @quelqu'un "Hé, j'ai vu ton post !"
xurl dms -n 25

Téléchargement de médias

# Détection automatique du type
xurl media upload photo.jpg
xurl media upload video.mp4

# Type/catégorie explicite
xurl media upload --media-type image/jpeg --category tweet_image photo.jpg

# Les vidéos nécessitent un traitement côté serveur — vérifiez le statut (ou interrogez)
xurl media status ID_MÉDIA
xurl media status --wait ID_MÉDIA

# Workflow complet
xurl media upload meme.png                  # renvoie l'id du média
xurl post "lol" --media-id ID_MÉDIA

---

Accès API brut

Les raccourcis couvrent les opérations courantes. Pour tout le reste, utilisez le mode brut de type curl contre n'importe quel point d'accès de l'API X v2 :

# GET
xurl /2/users/me

# POST avec corps JSON
xurl -X POST /2/tweets -d '{"text":"Bonjour le monde !"}'

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

# En-têtes personnalisés
xurl -H "Content-Type: application/json" /2/some/endpoint

# Forcer le streaming
xurl -s /2/tweets/search/stream

# Les URL complètes fonctionnent aussi
xurl https://api.x.com/2/users/me

---

Indicateurs globaux

Indicateur	Court	Description
--app		Utiliser une application enregistrée spécifique (remplace la valeur par défaut)
--auth		Forcer le type d'authentification : oauth1, oauth2, ou app
--username	-u	Quel compte OAuth2 utiliser (si plusieurs existent)
--verbose	-v	Interdit dans les sessions d'agent — fuit les en-têtes d'authentification
--trace	-t	Ajouter l'en-tête de trace X-B3-Flags: 1

---

Streaming

Les points d'accès de streaming sont détectés automatiquement. Les connus incluent :

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

Forcez le streaming sur n'importe quel point d'accès avec -s.

---

Format de sortie

Toutes les commandes renvoient du JSON sur la sortie standard. La structure reflète l'API X v2 :

{ "data": { "id": "1234567890", "text": "Bonjour le monde !" } }

Les erreurs sont aussi au format JSON :

{ "errors": [ { "message": "Non autorisé", "code": 403 } ] }

---

Workflows courants

Publier avec une image

xurl media upload photo.jpg
xurl post "Regardez cette photo !" --media-id ID_MÉDIA

Répondre à une conversation

xurl read https://x.com/user/status/1234567890
xurl reply 1234567890 "Voici mes réflexions..."

Rechercher et interagir

xurl search "sujet d'intérêt" -n 10
xurl like ID_POST_DES_RÉSULTATS
xurl reply ID_POST_DES_RÉSULTATS "Excellente remarque !"

Vérifier votre activité

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

Applications multiples (identifiants préconfigurés manuellement)

xurl auth default prod alice               # application prod, utilisateur alice
xurl --app staging /2/users/me             # ponctuel contre staging

---

Gestion des erreurs

• Code de sortie non nul en cas d'erreur.
• Les erreurs API sont toujours affichées au format JSON sur la sortie standard, vous pouvez donc les analyser.
• Erreurs d'authentification → demandez à l'utilisateur de réexécuter xurl auth oauth2 en dehors de la session d'agent.
• Les commandes qui nécessitent l'ID utilisateur de l'appelant (like, repost, bookmark, follow, etc.) le récupéreront automatiquement via /2/users/me. Un échec d'authentification se manifeste par une erreur d'authentification.

---

Workflow de l'agent

1. Vérifiez les prérequis : xurl --help et xurl auth status.
2. Avant d'utiliser xurl search, vérifiez l'intention. Utilisez-le lorsque la tâche nécessite des objets de post réels, le contexte du compte authentifié, ou mène à une action d'écriture X — c'est la bonne surface lorsque l'utilisateur souhaite des posts avec lesquels il peut interagir, et pas seulement un résumé d'un sujet.
3. Vérifiez que l'application par défaut a des identifiants. Analysez la sortie de auth status. L'application par défaut est marquée avec ▸. Si l'application par défaut affiche oauth2: (aucun) mais qu'une autre application a un utilisateur oauth2 valide, dites à l'utilisateur d'exécuter xurl auth default <cette-app> pour corriger. C'est l'erreur de configuration la plus courante — l'utilisateur a ajouté une application avec un nom personnalisé mais ne l'a jamais définie comme application par défaut, donc xurl continue d'essayer le profil default vide.
4. Si l'authentification est complètement absente, arrêtez-vous et dirigez l'utilisateur vers la section "Configuration utilisateur unique" — ne tentez PAS d'enregistrer des applications ou de transmettre des secrets vous-même.
5. Commencez par une lecture peu coûteuse (xurl whoami, xurl user @identifiant, xurl search ... -n 3) pour confirmer la joignabilité.
6. Confirmez le post/l'utilisateur cible et l'intention de l'utilisateur avant toute action d'écriture (post, répondre, liker, reposter, MP, follow, bloquer, supprimer).
7. Seule la sortie de la commande xurl (ou la réponse brute de l'API X) prouve qu'une action X modifiant l'état a eu lieu. Ne signalez jamais une écriture comme effectuée sur la base d'une autre source — résultats de recherche, résumés ou contexte antérieur.
8. Utilisez la sortie JSON directement — chaque réponse est déjà structurée.
9. Ne collez jamais le contenu de ~/.xurl dans la conversation.

---

Dépannage

Symptôme	Cause	Correctif
Erreurs d'authentification après un flux OAuth réussi	Jeton enregistré dans l'application default (pas de client-id/secret) au lieu de votre application nommée	xurl auth oauth2 --app my-app puis xurl auth default my-app
unauthorized_client pendant OAuth	Type d'application défini sur "Application native" dans le tableau de bord X	Remplacez par "Application Web, application automatisée ou bot" dans les paramètres d'authentification utilisateur
UsernameNotFound ou 403 sur /2/users/me juste après OAuth	X ne renvoie pas l'identifiant de manière fiable depuis /2/users/me	Réexécutez xurl auth oauth2 --app my-app VOTRE_NOM_UTILISATEUR (xurl v1.1.0+) pour transmettre l'identifiant explicitement
401 sur chaque requête	Jeton expiré ou mauvaise application par défaut	Vérifiez xurl auth status — définissez l'application correcte comme application par défaut, ou réexécutez xurl auth oauth2
Les téléchargements de médias échouent	Fichier trop volumineux ou type MIME incorrect	Vérifiez les limites de fichiers de l'API X ; assurez-vous que le type MIME correspond au fichier