Lord1Egypt/awesome-skill-forge

xurl — X (Twitter) API via die offizielle CLI

xurl ist die offizielle CLI der X-Entwicklerplattform für die X-API. Sie unterstützt Kurzbefehle für häufige Aktionen UND rohen Curl-Zugriff auf jeden v2-Endpunkt. Alle Befehle geben JSON nach stdout aus.

Verwenden Sie diesen Skill für:

• Veröffentlichen, Antworten, Zitieren, Löschen von Beiträgen
• Suchen von Beiträgen und Lesen von Timelines/Erwähnungen
• Liken, Reposten, Bookmarken
• Folgen, Entfolgen, Blocken, Stummschalten
• Direktnachrichten
• Medien-Uploads (Bilder und Videos)
• Rohen Zugriff auf jeden X API v2-Endpunkt
• Multi-App / Multi-Account-Workflows

Dieser Skill ersetzt den älteren xitter-Skill (welcher eine Drittanbieter-Python-CLI verwendete). xurl wird vom X-Entwicklerplattform-Team gewartet, unterstützt OAuth 2.0 PKCE mit Auto-Refresh und deckt eine wesentlich größere API-Oberfläche ab.

---

Geheimnissicherheit (VERPFLICHTEND)

Kritische Regeln für den Betrieb in einer Agent-/LLM-Sitzung:

• Niemals ~/.xurl lesen, ausgeben, parsen, zusammenfassen, hochladen oder an den LLM-Kontext senden.
• Niemals den Benutzer bitten, Anmeldedaten/Token in den Chat einzufügen.
• Der Benutzer muss ~/.xurl manuell auf seinem eigenen Rechner mit den Geheimnissen befüllen. In Docker muss dies das ~ sein, das von Hermes-Tool-Subprozessen gesehen wird; siehe den Docker-Hinweis unten.
• Niemals Auth-Befehle mit Inline-Geheimnissen in Agent-Sitzungen empfehlen oder ausführen.
• Niemals --verbose / -v in Agent-Sitzungen verwenden – es kann Auth-Header/Token offenlegen.
• Um zu überprüfen, ob Anmeldedaten vorhanden sind, nur verwenden: xurl auth status.

Verbotene Flags in Agent-Befehlen (sie akzeptieren Inline-Geheimnisse): --bearer-token, --consumer-key, --consumer-secret, --access-token, --token-secret, --client-id, --client-secret

Die Registrierung von App-Anmeldedaten und der Anmeldedatenwechsel müssen vom Benutzer manuell außerhalb der Agent-Sitzung durchgeführt werden. Nachdem die Anmeldedaten registriert sind, authentifiziert sich der Benutzer mit xurl auth oauth2 – ebenfalls außerhalb der Agent-Sitzung. Token verbleiben im YAML-Format in ~/.xurl. Jede App hat isolierte Token. OAuth 2.0-Token erneuern sich automatisch.

---

Installation

Wählen Sie EINE Methode. Unter Linux sind das Shell-Skript oder go install am einfachsten.

# Shell-Skript (installiert nach ~/.local/bin, kein sudo, funktioniert unter 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

Überprüfung:

xurl --help
xurl auth status

Wenn xurl installiert ist, aber auth status keine Apps oder Token anzeigt, muss der Benutzer die Authentifizierung manuell abschließen – siehe den nächsten Abschnitt.

---

Einmalige Benutzereinrichtung (Benutzer führt diese außerhalb des Agenten aus)

Diese Schritte müssen direkt vom Benutzer ausgeführt werden, NICHT vom Agenten, da sie das Einfügen von Geheimnissen beinhalten. Verweisen Sie den Benutzer auf diesen Block; führen Sie ihn nicht für ihn aus.

1. Erstellen oder öffnen Sie eine App unter https://developer.x.com/en/portal/dashboard

2. Setzen Sie die Weiterleitungs-URI auf http://localhost:8080/callback

3. Kopieren Sie die Client-ID und das Client-Geheimnis der App

4. Registrieren Sie die App lokal (Benutzer führt dies aus):

   xurl auth apps add my-app --client-id YOUR_CLIENT_ID --client-secret YOUR_CLIENT_SECRET
   

5. Authentifizieren Sie sich (geben Sie --app an, um das Token an Ihre App zu binden):

   xurl auth oauth2 --app my-app
   

   (Dies öffnet einen Browser für den OAuth 2.0 PKCE-Ablauf.)

   Wenn X nach dem OAuth einen UsernameNotFound-Fehler oder 403 beim /2/users/me-Lookup zurückgibt, übergeben Sie Ihren Handle explizit (xurl v1.1.0+):

   xurl auth oauth2 --app my-app YOUR_USERNAME
   

   Dies bindet das Token an Ihren Handle und überspringt den fehlerhaften /2/users/me-Aufruf.

6. Setzen Sie die App als Standard, sodass alle Befehle sie verwenden:

   xurl auth default my-app
   

7. Überprüfen:

   xurl auth status
   xurl whoami
   

Danach kann der Agent jeden unten stehenden Befehl ohne weitere Einrichtung verwenden. OAuth 2.0-Token erneuern sich automatisch.

Häufige Falle: Wenn Sie --app my-app bei xurl auth oauth2 weglassen, wird das OAuth-Token im integrierten default-App-Profil gespeichert – welches keine Client-ID oder kein Client-Geheimnis hat. Befehle schlagen dann mit Authentifizierungsfehlern fehl, obwohl der OAuth-Ablauf erfolgreich schien. Wenn Sie darauf stoßen, führen Sie xurl auth oauth2 --app my-app und xurl auth default my-app erneut aus.

Docker HOME-Falle: Im offiziellen Hermes-Docker-Layout ist /opt/data das HERMES_HOME, aber Hermes-Tool-Subprozesse verwenden /opt/data/home als HOME. Das bedeutet, dass ~/.xurl für Hermes-ausgeführte xurl-Befehle zu /opt/data/home/.xurl aufgelöst wird, nicht zu /opt/data/.xurl. Führen Sie die Benutzereinrichtung mit demselben HOME aus:

HOME=/opt/data/home xurl auth apps add my-app --client-id YOUR_CLIENT_ID --client-secret YOUR_CLIENT_SECRET
HOME=/opt/data/home xurl auth oauth2 --app my-app YOUR_USERNAME
HOME=/opt/data/home xurl auth default my-app YOUR_USERNAME
HOME=/opt/data/home xurl auth status

Wenn HOME=/opt/data xurl auth status erfolgreich ist, aber HOME=/opt/data/home xurl auth status keine Apps oder Token anzeigt, werden Hermes-Tool-Aufrufe die Anmeldedaten nicht sehen.

---

Kurzreferenz

Aktion	Befehl
Veröffentlichen	xurl post "Hallo Welt!"
Antworten	xurl reply POST_ID "Toller Beitrag!"
Zitieren	xurl quote POST_ID "Meine Meinung"
Beitrag löschen	xurl delete POST_ID
Beitrag lesen	xurl read POST_ID
Beiträge suchen	xurl search "QUERY" -n 10
Wer bin ich	xurl whoami
Benutzer nachschlagen	xurl user @handle
Startseiten-Timeline	xurl timeline -n 20
Erwähnungen	xurl mentions -n 10
Liken / Unlike	xurl like POST_ID / xurl unlike POST_ID
Reposten / Rückgängig	xurl repost POST_ID / xurl unrepost POST_ID
Bookmarken / Entfernen	xurl bookmark POST_ID / xurl unbookmark POST_ID
Lesezeichen / Likes auflisten	xurl bookmarks -n 10 / xurl likes -n 10
Folgen / Entfolgen	xurl follow @handle / xurl unfollow @handle
Gefolgt / Follower	xurl following -n 20 / xurl followers -n 20
Blocken / Entblocken	xurl block @handle / xurl unblock @handle
Stummschalten / Lautschalten	xurl mute @handle / xurl unmute @handle
DM senden	xurl dm @handle "Nachricht"
DMs auflisten	xurl dms -n 10
Medien hochladen	xurl media upload path/to/file.mp4
Medienstatus	xurl media status MEDIA_ID
Apps auflisten	xurl auth apps list
App entfernen	xurl auth apps remove NAME
Standard-App setzen	xurl auth default APP_NAME [USERNAME]
App pro Anfrage	xurl --app NAME /2/users/me
Auth-Status	xurl auth status

Hinweise:

• POST_ID akzeptiert auch vollständige URLs (z. B. https://x.com/user/status/1234567890) – xurl extrahiert die ID.
• Benutzernamen funktionieren mit oder ohne führendem @.

---

Befehlsdetails

Veröffentlichen

xurl post "Hallo Welt!"
xurl post "Schau dir das an" --media-id MEDIA_ID
xurl post "Thread-Bilder" --media-id 111 --media-id 222

xurl reply 1234567890 "Guter Punkt!"
xurl reply https://x.com/user/status/1234567890 "Zustimmung!"
xurl reply 1234567890 "Schau dir das an" --media-id MEDIA_ID

xurl quote 1234567890 "Meine Gedanken dazu"
xurl delete 1234567890

Lesen & Suchen

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

Verwenden Sie für X-Artikel den Roh-API-Modus anstelle des read-Kurzbefehls. xurl read erwartet eine Beitrags-ID oder -URL; setzen Sie read nicht vor einen /2/tweets/...-Endpunkt. Fordern Sie das article-Tweet-Feld an und extrahieren Sie data.article.plain_text aus der JSON-Antwort:

xurl --app APP_NAME '/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'

Benutzer, Timeline, Erwähnungen

xurl whoami
xurl user elonmusk
xurl user @XDevelopers

xurl timeline -n 25
xurl mentions -n 20

Interaktionen

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

Sozialer Graph

xurl follow @XDevelopers
xurl unfollow @XDevelopers

xurl following -n 50
xurl followers -n 50

# Graph eines anderen Benutzers
xurl following --of elonmusk -n 20
xurl followers --of elonmusk -n 20

xurl block @spammer
xurl unblock @spammer
xurl mute @annoying
xurl unmute @annoying

Direktnachrichten

xurl dm @someuser "Hey, deinen Beitrag gesehen!"
xurl dms -n 25

Medien-Upload

# Automatische Typenerkennung
xurl media upload photo.jpg
xurl media upload video.mp4

# Expliziter Typ/Kategorie
xurl media upload --media-type image/jpeg --category tweet_image photo.jpg

# Videos benötigen serverseitige Verarbeitung – Status prüfen (oder abfragen)
xurl media status MEDIA_ID
xurl media status --wait MEDIA_ID

# Vollständiger Workflow
xurl media upload meme.png                  # gibt Medien-ID zurück
xurl post "lol" --media-id MEDIA_ID

---

Roh-API-Zugriff

Die Kurzbefehle decken häufige Operationen ab. Verwenden Sie für alles andere den rohen Curl-ähnlichen Modus gegen jeden X API v2-Endpunkt:

# GET
xurl /2/users/me

# POST mit JSON-Body
xurl -X POST /2/tweets -d '{"text":"Hallo Welt!"}'

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

# Benutzerdefinierte Header
xurl -H "Content-Type: application/json" /2/some/endpoint

# Streaming erzwingen
xurl -s /2/tweets/search/stream

# Vollständige URLs funktionieren auch
xurl https://api.x.com/2/users/me

---

Globale Flags

Flag	Kurz	Beschreibung
--app		Eine bestimmte registrierte App verwenden (überschreibt Standard)
--auth		Auth-Typ erzwingen: oauth1, oauth2 oder app
--username	-u	Welches OAuth2-Konto verwendet werden soll (falls mehrere vorhanden)
--verbose	-v	In Agent-Sitzungen verboten – gibt Auth-Header preis
--trace	-t	X-B3-Flags: 1-Trace-Header hinzufügen

---

Streaming

Streaming-Endpunkte werden automatisch erkannt. Bekannte sind:

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

Streaming auf jedem Endpunkt mit -s erzwingen.

---

Ausgabeformat

Alle Befehle geben JSON nach stdout aus. Die Struktur spiegelt X API v2 wider:

{ "data": { "id": "1234567890", "text": "Hallo Welt!" } }

Fehler sind ebenfalls JSON:

{ "errors": [ { "message": "Nicht autorisiert", "code": 403 } ] }

---

Häufige Workflows

Beitrag mit Bild

xurl media upload photo.jpg
xurl post "Schau dir dieses Foto an!" --media-id MEDIA_ID

Auf eine Konversation antworten

xurl read https://x.com/user/status/1234567890
xurl reply 1234567890 "Hier sind meine Gedanken..."

Suchen und interagieren

xurl search "interessantes Thema" -n 10
xurl like POST_ID_FROM_RESULTS
xurl reply POST_ID_FROM_RESULTS "Guter Punkt!"

Eigene Aktivitäten prüfen

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

Mehrere Apps (Anmeldedaten manuell vorkonfiguriert)

xurl auth default prod alice               # prod-App, Benutzer alice
xurl --app staging /2/users/me             # einmaliger Aufruf gegen staging

---

Fehlerbehandlung

• Exit-Code ungleich Null bei jedem Fehler.
• API-Fehler werden dennoch als JSON nach stdout ausgegeben, sodass Sie sie parsen können.
• Auth-Fehler → Benutzer soll xurl auth oauth2 außerhalb der Agent-Sitzung erneut ausführen.
• Befehle, die die Benutzer-ID des Aufrufers benötigen (like, repost, bookmark, follow, etc.), rufen diese automatisch über /2/users/me ab. Ein Auth-Fehler dort erscheint als Auth-Fehler.

---

Agenten-Workflow

1. Voraussetzungen prüfen: xurl --help und xurl auth status.
2. Überprüfen, ob die Standard-App Anmeldedaten hat. Die Ausgabe von auth status parsen. Die Standard-App ist mit ▸ markiert. Wenn die Standard-App oauth2: (none) anzeigt, aber eine andere App einen gültigen oauth2-Benutzer hat, sagen Sie dem Benutzer, er solle xurl auth default <diese-app> ausführen, um dies zu beheben. Dies ist der häufigste Einrichtungsfehler – der Benutzer hat eine App mit einem benutzerdefinierten Namen hinzugefügt, aber nie als Standard festgelegt, sodass xurl weiterhin das leere default-Profil verwendet.
3. Wenn Auth vollständig fehlt, anhalten und den Benutzer auf den Abschnitt "Einmalige Benutzereinrichtung" verweisen – NICHT versuchen, Apps selbst zu registrieren oder Geheimnisse zu übergeben.
4. Mit einem günstigen Lesezugriff beginnen (xurl whoami, xurl user @handle, xurl search ... -n 3), um die Erreichbarkeit zu bestätigen.
5. Vor jeder Schreibaktion (post, reply, like, repost, DM, follow, block, delete) den Ziel-Beitrag/Benutzer und die Absicht des Benutzers bestätigen.
6. Die JSON-Ausgabe direkt verwenden – jede Antwort ist bereits strukturiert.
7. Niemals den Inhalt von ~/.xurl zurück in die Konversation einfügen.

---

Fehlerbehebung

Symptom	Ursache	Behebung
Auth-Fehler nach erfolgreichem OAuth-Ablauf	Token in der default-App gespeichert (keine Client-ID/Geheimnis) anstatt in Ihrer benannten App	xurl auth oauth2 --app my-app dann xurl auth default my-app
unauthorized_client während OAuth	App-Typ im X-Dashboard auf "Native App" gesetzt	Ändern Sie in den Benutzerauthentifizierungseinstellungen auf "Web-App, automatisierte App oder Bot"
UsernameNotFound oder 403 auf /2/users/me direkt nach OAuth	X gibt den Benutzernamen von /2/users/me nicht zuverlässig zurück	Führen Sie xurl auth oauth2 --app my-app YOUR_USERNAME (xurl v1.1.0+) erneut aus, um den Handle explizit zu übergeben
401 bei jeder Anfrage	Token abgelaufen oder falsche Standard-App	xurl auth status prüfen – sicherstellen, dass ▸ auf eine App mit oauth2-Tokens zeigt
client-forbidden / client-not-enrolled	Problem mit der X-Plattform-Anmeldung	Dashboard → Apps → Verwalten → Zum Paket "Pay-per-use" wechseln → Produktionsumgebung
CreditsDepleted	Guthaben von $0 auf der X-API	Credits kaufen (min. $5) in der Developer Console → Abrechnung
media processing failed beim Bild-Upload	Standardkategorie ist amplify_video	--category tweet_image --media-type image/png hinzufügen
Zwei "Client-Secret"-Werte im X-Dashboard	UI-Fehler – der erste ist tatsächlich die Client-ID	Auf der Seite "Keys and tokens" bestätigen; ID endet mit MTpjaQ

---

Hinweise

• Ratenlimit: X setzt endpoint-spezifische Ratenlimits. Ein 429 bedeutet warten und wiederholen. Schreibendpunkte (post, reply, like, repost) haben strengere Limits als Lesezugriffe.
• Scopes: OAuth 2.0-Token verwenden breite Scopes – tweet.read, tweet.write, users.read, dm.read, dm.write, follows.read, follows.write, offline.access. Alle wichtigen Operationen werden damit abgedeckt.