Lord1Egypt/awesome-skill-forge

xurl — API X (Twitter) via l'interface en ligne de commande officielle

xurl est l'interface en ligne de commande officielle de la plateforme de développeurs X pour l'API X. Elle prend en charge des commandes raccourcies pour les actions courantes ET un accès brut de type curl à tout endpoint v2. Toutes les commandes renvoient du JSON sur la sortie standard.

Utilisez cette compétence pour :

• publier, répondre, citer, supprimer des publications
• rechercher des publications et lire les timelines/mentions
• liker, republier, mettre en favori
• suivre, ne plus suivre, bloquer, mettre en sourdine
• messages directs
• upload de médias (images et vidéos)
• accès brut à tout endpoint de l'API X v2
• workflows multi-applications / multi-comptes

Cette compétence remplace l'ancienne compétence xitter (qui utilisait une interface Python tierce). xurl est maintenu par l'équipe de la plateforme de développeurs X, prend en charge OAuth 2.0 PKCE avec auto-rafraîchissement, et couvre une surface d'API considérablement plus large.

---

Sécurité des secrets (OBLIGATOIRE)

Règles critiques lors de l'utilisation 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/tokens 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/tokens d'authentification.
• Pour vérifier l'existence des identifiants, utilisez uniquement : xurl auth status.

Drapeaux 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 de l'agent. Après l'enregistrement des identifiants, l'utilisateur s'authentifie avec xurl auth oauth2 — également en dehors de la session de l'agent. Les tokens persistent dans ~/.xurl au format YAML. Chaque application a des tokens isolés. Les tokens OAuth 2.0 s'auto-rafraîchissent.

---

Installation

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

# Script shell (installe dans ~/.local/bin, pas besoin de 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érification :

xurl --help
xurl auth status

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

---

Configuration utilisateur unique (l'utilisateur exécute ces étapes 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 pour lui.

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 ceci) :

   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 token à 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, passez votre pseudo explicitement (xurl v1.1.0+) :

   xurl auth oauth2 --app my-app VOTRE_PSEUDO
   

   Cela lie le token à votre pseudo 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 tokens OAuth 2.0 s'auto-rafraîchissent.

Piège courant : Si vous omettez --app my-app de xurl auth oauth2, le token 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, relancez xurl auth oauth2 --app my-app et xurl auth default my-app.

Piège Docker HOME : Dans la disposition Docker officielle d'Hermes, /opt/data est HERMES_HOME, mais les sous-processus de l'outil Hermes utilisent /opt/data/home comme HOME. Cela signifie que ~/.xurl se résout en /opt/data/home/.xurl pour les commandes xurl exécutées par Hermes, et non /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_PSEUDO
HOME=/opt/data/home xurl auth default my-app VOTRE_PSEUDO
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 token, 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 "Belle publication !"
Citer	xurl quote ID_POST "Mon avis"
Supprimer une publication	xurl delete ID_POST
Lire une publication	xurl read ID_POST
Rechercher des publications	xurl search "REQUETE" -n 10
Qui suis-je	xurl whoami
Rechercher un utilisateur	xurl user @pseudo
Fil d'actualité	xurl timeline -n 20
Mentions	xurl mentions -n 10
Liker / Ne plus liker	xurl like ID_POST / xurl unlike ID_POST
Republier / 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 @pseudo / xurl unfollow @pseudo
Abonnements / Abonnés	xurl following -n 20 / xurl followers -n 20
Bloquer / Débloquer	xurl block @pseudo / xurl unblock @pseudo
Mettre en sourdine / Réactiver	xurl mute @pseudo / xurl unmute @pseudo
Envoyer un MP	xurl dm @pseudo "message"
Lister les MP	xurl dms -n 10
Uploader un média	xurl media upload chemin/vers/fichier.mp4
Statut du média	xurl media status ID_MEDIA
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 [PSEUDO]
Application par requête	xurl --app NOM /2/users/me
Statut de l'authentification	xurl auth status

Notes :

• ID_POST accepte également les URL complètes (par ex. https://x.com/user/status/1234567890) — xurl extrait l'ID.
• Les pseudos fonctionnent avec ou sans @ au début.

---

Détails des commandes

Publication

xurl post "Bonjour le monde !"
xurl post "Regarde ça" --media-id ID_MEDIA
xurl post "Pics du fil" --media-id 111 --media-id 222

xurl reply 1234567890 "Bonne remarque !"
xurl reply https://x.com/user/status/1234567890 "D'accord !"
xurl reply 1234567890 "Regarde ça" --media-id ID_MEDIA

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

Lecture et recherche

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

Pour les articles X, utilisez le mode API brut au lieu du raccourci read. xurl read s'attend à un ID de publication ou une URL de publication ; ne mettez pas read avant un endpoint /2/tweets/.... Demandez le champ article du tweet et ingérez data.article.plain_text depuis 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 @quelquun "Hé, j'ai vu ta publication !"
xurl dms -n 25

Upload 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_MEDIA
xurl media status --wait ID_MEDIA

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

---

Accès brut à l'API

Les raccourcis couvrent les opérations courantes. Pour tout le reste, utilisez le mode brut de type curl contre tout endpoint 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

---

Drapeaux globaux

Drapeau	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 endpoints de streaming sont détectés automatiquement. Les plus connus sont :

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

Forcez le streaming sur n'importe quel endpoint 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 également en JSON :

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

---

Workflows courants

Publier avec une image

xurl media upload photo.jpg
xurl post "Regarde cette photo !" --media-id ID_MEDIA

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_RESULTATS
xurl reply ID_POST_DES_RESULTATS "Bonne 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             # utilisation ponctuelle sur staging

---

Gestion des erreurs

• Code de sortie non nul en cas d'erreur.
• Les erreurs de l'API sont toujours affichées en JSON sur la sortie standard, vous pouvez donc les analyser.
• Erreurs d'authentification → demandez à l'utilisateur de relancer xurl auth oauth2 en dehors de la session de l'agent.
• Les commandes qui ont besoin de 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 présente comme une erreur d'authentification.

---

Workflow de l'agent

1. Vérifiez les prérequis : xurl --help et xurl auth status.
2. 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 par ▸. 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 le problème. 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.
3. Si l'authentification est totalement absente, arrêtez-vous et dirigez l'utilisateur vers la section "Configuration utilisateur unique" — N'essayez PAS d'enregistrer vous-même des applications ou de passer des secrets.
4. Commencez par une lecture peu coûteuse (xurl whoami, xurl user @pseudo, xurl search ... -n 3) pour confirmer l'accessibilité.
5. Confirmez la publication/utilisateur cible et l'intention de l'utilisateur avant toute action d'écriture (poster, répondre, liker, republier, MP, suivre, bloquer, supprimer).
6. Utilisez directement la sortie JSON — chaque réponse est déjà structurée.
7. 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	Token enregistré dans l'application default (sans client-id/secret) au lieu de votre application nommée	xurl auth oauth2 --app my-app puis xurl auth default my-app
unauthorized_client lors de l'OAuth	Type d'application défini sur "Application native" dans le tableau de bord X	Passez à "Application web, application automatisée ou bot" dans les paramètres d'authentification utilisateur
UsernameNotFound ou 403 sur /2/users/me juste après l'OAuth	X ne renvoie pas le pseudo de manière fiable depuis /2/users/me	Relancez xurl auth oauth2 --app my-app VOTRE_PSEUDO (xurl v1.1.0+) pour passer le pseudo explicitement
401 sur chaque requête	Token expiré ou mauvaise application par défaut	Vérifiez xurl auth status — assurez-vous que ▸ pointe vers une application avec des tokens oauth2
client-forbidden / client-not-enrolled	Problème d'inscription à la plateforme X	Tableau de bord → Applications → Gérer → Passer au forfait "Pay-per-use" → Environnement de production
CreditsDepleted	Solde $0 sur l'API X	Achetez des crédits (min. $5) dans la Console développeur → Facturation
media processing failed lors de l'upload d'image	La catégorie par défaut est amplify_video	Ajoutez --category tweet_image --media-type image/png
Deux valeurs "Client Secret" dans le tableau de bord X	Bug de l'interface — la première est en fait le Client ID	Confirmez sur la page "Clés et tokens" ; l'ID se termine par MTpjaQ

---

Notes

• Limites de débit : X applique des limites de débit par endpoint. Un 429 signifie attendre et réessayer. Les endpoints d'écriture (poster, répondre, liker, republier) ont des limites plus strictes que les lectures.
• Portées : Les tokens OAuth 2.0 utilisent des portées étendues