Samin12/skills

xurl — X (Twitter) API über die Offizielle CLI

xurl ist die offizielle CLI der X-Entwicklerplattform für die X-API. Es unterstützt Kurzbefehle für häufige Aktionen sowie rohen curl-ähnlichen Zugriff auf alle v2-Endpunkte. Alle Befehle geben JSON über die Standardausgabe aus.

Nutzen Sie dieses Skill für:

• Veröffentlichen, Antworten, Zitieren, Löschen von Beiträgen
• Suche nach rohen Posts (tatsächliches Post-JSON mit IDs, mit denen interagiert werden kann) und Lesen von Timelines/Erwähnungen
• Liken, Reposten, Bookmarken
• Folgen, Entfolgen, Blockieren, Stummschalten
• Direktnachrichten
• Medien-Uploads (Bilder und Videos)
• Rohen Zugriff auf jeden X-API-v2-Endpunkt
• Multi-App / Multi-Account-Workflows

Dieses Skill ersetzt das ältere xitter-Skill (das 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.

---

Sicherheit von Geheimnissen (ZWINGEND)

Wichtige Regeln für den Betrieb in einer Agenten-/LLM-Sitzung:

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

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

Die Registrierung von App-Anmeldeinformationen und deren Rotation muss vom Benutzer manuell außerhalb der Agentensitzung durchgeführt werden. Nach der Registrierung der Anmeldeinformationen authentifiziert sich der Benutzer mit xurl auth oauth2 – ebenfalls außerhalb der Agentensitzung. Tokens werden in YAML in ~/.xurl gespeichert. Jede App hat isolierte Tokens. OAuth-2.0-Tokens werden automatisch erneuert.

---

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, auth status aber keine Apps oder Tokens anzeigt, muss der Benutzer die Authentifizierung manuell abschließen – siehe nächster Abschnitt.

---

Einmalige Benutzereinrichtung (vom Benutzer außerhalb des Agenten auszuführen)

Diese Schritte müssen direkt vom Benutzer durchgefü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-Secret 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 (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-Flow.)

   Wenn X einen UsernameNotFound-Fehler oder 403 bei der post-OAuth /2/users/me-Abfrage 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üfung:

   xurl auth status
   xurl whoami
   

Danach kann der Agent jeden untenstehenden Befehl ohne weitere Einrichtung verwenden. OAuth-2.0-Tokens werden automatisch erneuert.

Häufige Fehlerquelle: Wenn Sie --app my-app bei xurl auth oauth2 weglassen, wird das OAuth-Token im integrierten default-App-Profil gespeichert – das keine Client-ID oder Client-Secret hat. Befehle werden mit Auth-Fehlern fehlschlagen, auch wenn der OAuth-Flow scheinbar erfolgreich war. Wenn dies passiert, führen Sie xurl auth oauth2 --app my-app und xurl auth default my-app erneut aus.

Docker-HOME-Fehlerquelle: Im offiziellen Hermes-Docker-Layout ist /opt/data HERMES_HOME, aber Hermes-Tool-Unterprozesse verwenden /opt/data/home als HOME. Das bedeutet, dass ~/.xurl für von 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 Tokens anzeigt, werden Hermes-Tool-Aufrufe die Anmeldeinformationen nicht sehen.

---

Kurzreferenz

Aktion	Befehl
Posten	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 "ABFRAGE" -n 10
Wer bin ich	xurl whoami
Benutzer nachschlagen	xurl user @handle
Startseiten-Timeline	xurl timeline -n 20
Erwähnungen	xurl mentions -n 10
Like / Unlike	xurl like POST_ID / xurl unlike POST_ID
Reposten / Rückgängig	xurl repost POST_ID / xurl unrepost POST_ID
Bookmark / Entfernen	xurl bookmark POST_ID / xurl unbookmark POST_ID
Bookmarks / 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
Blockieren / Entblocken	xurl block @handle / xurl unblock @handle
Stummschalten / Entstummen	xurl mute @handle / xurl unmute @handle
DM senden	xurl dm @handle "Nachricht"
DMs auflisten	xurl dms -n 10
Medien hochladen	xurl media upload pfad/zu/datei.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ührendes @.

---

Befehlsdetails

Beiträge 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 "Stimme zu!"
xurl reply 1234567890 "Schau dir das an" --media-id MEDIA_ID

xurl quote 1234567890 "Meine Gedanken dazu"
xurl delete 1234567890

Lesen & Suchen

xurl search durchsucht den X-Index als Ihr authentifiziertes Konto und gibt rohe Post-Objekte zurück – IDs, Autoren, vollständigen Text – sodass Ergebnisse sofort verwendet werden können (antworten, liken, reposten, zitieren). Verwenden Sie es, wenn Sie die tatsächlichen Beiträge benötigen und nicht nur eine zusammengefasste Antwort zu einem Thema.

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

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

Verwenden Sie für X-Artikel den rohen API-Modus anstelle des read-Kurzbefehls. xurl read erwartet eine Post-ID oder Post-URL; setzen Sie read nicht vor einen /2/tweets/...-Endpunkt. Fordern Sie das article-Tweet-Feld an und entnehmen 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

Soziales Netzwerk

xurl follow @XDevelopers
xurl unfollow @XDevelopers

xurl following -n 50
xurl followers -n 50

# Netzwerk 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, habe 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

---

Roher API-Zugriff

Die Kurzbefehle decken die häufigsten 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 ebenfalls
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 verwenden (falls mehrere vorhanden)
--verbose	-v	In Agentensitzungen 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

Erzwingen Sie Streaming für jeden Endpunkt mit -s.

---

Ausgabeformat

Alle Befehle geben JSON über die Standardausgabe aus. Die Struktur spiegelt die X-API v2 wider:

{ "data": { "id": "1234567890", "text": "Hello world!" } }

Fehler werden ebenfalls als JSON ausgegeben:

{ "errors": [ { "message": "Not authorized", "code": 403 } ] }

---

Häufige Workflows

Beitrag mit einem 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 "Thema von Interesse" -n 10
xurl like POST_ID_FROM_RESULTS
xurl reply POST_ID_FROM_RESULTS "Guter Punkt!"

Eigene Aktivität prüfen

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

Mehrere Apps (Anmeldedaten manuell vorkonfiguriert)

xurl auth default prod alice               # App prod, Benutzer alice
xurl --app staging /2/users/me             # Einmalige Verwendung von staging

---

Fehlerbehandlung

• Exit-Code ungleich Null bei jedem Fehler.
• API-Fehler werden weiterhin als JSON auf der Standardausgabe ausgegeben, sodass Sie sie parsen können.
• Auth-Fehler → Lassen Sie den Benutzer xurl auth oauth2 außerhalb der Agentensitzung erneut ausführen.
• Befehle, die die Benutzer-ID des Aufrufers benötigen (like, repost, bookmark, follow usw.), rufen diese automatisch über /2/users/me ab. Ein Auth-Fehler dort zeigt sich als Auth-Fehler.

---

Agenten-Workflow

1. Voraussetzungen prüfen: xurl --help und xurl auth status.
2. Überprüfen Sie vor der Verwendung von xurl search die Absicht. Greifen Sie darauf zu, wenn die Aufgabe tatsächliche Post-Objekte, Kontext des authentifizierten Kontos oder eine schreibende Aktion auf X erfordert – es ist die richtige Oberfläche, wenn der Benutzer Beiträge wünscht, mit denen interagiert werden kann, nicht nur eine Zusammenfassung eines Themas.
3. Prüfen Sie, ob die Standard-App Anmeldedaten hat. Parsen Sie die auth status-Ausgabe. 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 das Problem zu beheben. Dies ist der häufigste Einrichtungsfehler – der Benutzer hat eine App mit einem benutzerdefinierten Namen hinzugefügt, aber nie als Standard gesetzt, sodass xurl weiterhin das leere default-Profil verwendet.
4. Wenn die Authentifizierung vollständig fehlt, stoppen Sie und verweisen Sie den Benutzer auf den Abschnitt „Einmalige Benutzereinrichtung“ – versuchen Sie NICHT, selbst Apps zu registrieren oder Geheimnisse zu übergeben.
5. Beginnen Sie mit einer kostengünstigen Leseoperation (xurl whoami, xurl user @handle, xurl search ... -n 3), um die Erreichbarkeit zu bestätigen.
6. Bestätigen Sie den Zielbeitrag/-benutzer und die Absicht des Benutzers vor jeder schreibenden Aktion (post, reply, like, repost, DM, follow, block, delete).
7. Nur die Ausgabe des xurl-Befehls (oder die rohe X-API-Antwort) beweist, dass eine zustandsändernde Aktion auf X stattgefunden hat. Melden Sie eine Schreibaktion niemals als erledigt, basierend auf einer anderen Quelle – Suchergebnisse, Zusammenfassungen oder vorherigem Kontext.
8. Verwenden Sie die JSON-Ausgabe direkt – jede Antwort ist bereits strukturiert.
9. Fügen Sie niemals den Inhalt von ~/.xurl in die Konversation ein.

---

Fehlerbehebung

Symptom	Ursache	Lösung
Auth-Fehler nach erfolgreichem OAuth-Flow	Token wurde im default-App (keine Client-ID/Secret) anstelle Ihrer benannten App gespeichert	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, Automated App or Bot“
UsernameNotFound oder 403 bei /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 erneut aus (xurl v1.1.0+), um den Handle explizit zu übergeben
401 bei jeder Anfrage	Token abgelaufen oder falsche Standard-App	Prüfen Sie xurl auth status