xurl – Writing & Content skill for AI agents

xurl — X (Twitter) API via the Official CLI

xurl is the X developer platform's official CLI for the X API. It supports shortcut commands for common actions AND raw curl-style access to any v2 endpoint. All commands return JSON to stdout.

Use this skill for:

• posting, replying, quoting, deleting posts
• searching for raw posts (actual post JSON with IDs you can engage with) and reading timelines/mentions
• liking, reposting, bookmarking
• following, unfollowing, blocking, muting
• direct messages
• media uploads (images and video)
• raw access to any X API v2 endpoint
• multi-app / multi-account workflows

This skill replaces the older xitter skill (which wrapped a third-party Python CLI). xurl is maintained by the X developer platform team, supports OAuth 2.0 PKCE with auto-refresh, and covers a substantially larger API surface.

---

Secret Safety (MANDATORY)

Critical rules when operating inside an agent/LLM session:

• Never read, print, parse, summarize, upload, or send ~/.xurl to LLM context.
• Never ask the user to paste credentials/tokens into chat.
• The user must fill ~/.xurl with secrets manually on their own machine. In Docker, this must be the ~ seen by Hermes tool subprocesses; see the Docker note below.
• Never recommend or execute auth commands with inline secrets in agent sessions.
• Never use --verbose / -v in agent sessions — it can expose auth headers/tokens.
• To verify credentials exist, only use: xurl auth status.

Forbidden flags in agent commands (they accept inline secrets):

--bearer-token, --consumer-key, --consumer-secret, --access-token, --token-secret, --client-id, --client-secret

App credential registration and credential rotation must be done by the user manually, outside the agent session. After credentials are registered, the user authenticates with xurl auth oauth2 — also outside the agent session. Tokens persist to ~/.xurl in YAML. Each app has isolated tokens. OAuth 2.0 tokens auto-refresh.

---

Installation

Pick ONE method. On Linux, the shell script or go install are the easiest.

# Shell script (installs to ~/.local/bin, no sudo, works on 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

Verify:

xurl --help
xurl auth status

If xurl is installed but auth status shows no apps or tokens, the user needs to complete auth manually — see the next section.

---

One-Time User Setup (user runs these outside the agent)

These steps must be performed by the user directly, NOT by the agent, because they involve pasting secrets. Direct the user to this block; do not execute it for them.

1. Create or open an app at https://developer.x.com/en/portal/dashboard

2. Set the redirect URI to http://localhost:8080/callback

3. Copy the app's Client ID and Client Secret

4. Register the app locally (user runs this):

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

5. Authenticate (specify --app to bind the token to your app):

   xurl auth oauth2 --app my-app
   

(This opens a browser for the OAuth 2.0 PKCE flow.)

If X returns a UsernameNotFound error or 403 on the post-OAuth /2/users/me lookup, pass your handle explicitly (xurl v1.1.0+):

   xurl auth oauth2 --app my-app YOUR_USERNAME
   

This binds the token to your handle and skips the broken /2/users/me call.

6. Set the app as default so all commands use it:

   xurl auth default my-app
   

7. Verify:

   xurl auth status
   xurl whoami
   

After this, the agent can use any command below without further setup. OAuth 2.0 tokens auto-refresh.

> Common pitfall: If you omit --app my-app from xurl auth oauth2, the OAuth token is saved to the built-in default app profile — which has no client-id or client-secret. Commands will fail with auth errors even though the OAuth flow appeared to succeed. If you hit this, re-run xurl auth oauth2 --app my-app and xurl auth default my-app.

> Docker HOME pitfall: In the official Hermes Docker layout, /opt/data is HERMES_HOME, but Hermes tool subprocesses use /opt/data/home as HOME. That means ~/.xurl resolves to /opt/data/home/.xurl for Hermes-run xurl commands, not /opt/data/.xurl. Run the user setup with the same HOME:

>

> 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
> 

> If HOME=/opt/data xurl auth status succeeds but HOME=/opt/data/home xurl auth status shows no apps or tokens, Hermes tool calls will not see the credentials.

---

Quick Reference

| Action | Command |

| --- | --- |

| Post | xurl post "Hello world!" |

| Reply | xurl reply POST_ID "Nice post!" |

| Quote | xurl quote POST_ID "My take" |

| Delete a post | xurl delete POST_ID |

| Read a post | xurl read POST_ID |

| Search posts | xurl search "QUERY" -n 10 |

| Who am I | xurl whoami |

| Look up a user | xurl user @handle |

| Home timeline | xurl timeline -n 20 |

| Mentions | xurl mentions -n 10 |

| Like / Unlike | xurl like POST_ID / xurl unlike POST_ID |

| Repost / Undo | xurl repost POST_ID / xurl unrepost POST_ID |

| Bookmark / Remove | xurl bookmark POST_ID / xurl unbookmark POST_ID |

| List bookmarks / likes | xurl bookmarks -n 10 / xurl likes -n 10 |

| Follow / Unfollow | xurl follow @handle / xurl unfollow @handle |

| Following / Followers | xurl following -n 20 / xurl followers -n 20 |

| Block / Unblock | xurl block @handle / xurl unblock @handle |

| Mute / Unmute | xurl mute @handle / xurl unmute @handle |

| Send DM | xurl dm @handle "message" |

| List DMs | xurl dms -n 10 |

| Upload media | xurl media upload path/to/file.mp4 |

| Media status | xurl media status MEDIA_ID |

| List apps | xurl auth apps list |

| Remove app | xurl auth apps remove NAME |

| Set default app | xurl auth default APP_NAME [USERNAME] |

| Per-request app | xurl --app NAME /2/users/me |

| Auth status | xurl auth status |

Notes:

• POST_ID accepts full URLs too (e.g. https://x.com/user/status/1234567890) — xurl extracts the ID.
• Usernames work with or without a leading @.

---

Command Details

Posting

xurl post "Hello world!"
xurl post "Check this out" --media-id MEDIA_ID
xurl post "Thread pics" --media-id 111 --media-id 222

xurl reply 1234567890 "Great point!"
xurl reply https://x.com/user/status/1234567890 "Agreed!"
xurl reply 1234567890 "Look at this" --media-id MEDIA_ID

xurl quote 1234567890 "Adding my thoughts"
xurl delete 1234567890

Reading & Search

xurl search queries the X index as your authenticated account and returns raw post objects — IDs, authors, full text — so results can be immediately engaged with (reply, like, repost, quote). Use it when you need the actual posts rather than a summarized answer about a topic.

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

For X Articles, use raw API mode instead of the read shortcut. xurl read

expects a post ID or post URL; do not put read before a /2/tweets/...

endpoint. Request the article tweet field and ingest data.article.plain_text

from the JSON response:

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'

Users, Timeline, 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

Social Graph

xurl follow @XDevelopers
xurl unfollow @XDevelopers

xurl following -n 50
xurl followers -n 50

# Another user's graph
xurl following --of elonmusk -n 20
xurl followers --of elonmusk -n 20

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

Direct Messages

xurl dm @someuser "Hey, saw your post!"
xurl dms -n 25

Media Upload

# Auto-detect type
xurl media upload photo.jpg
xurl media upload video.mp4

# Explicit type/category
xurl media upload --media-type image/jpeg --category tweet_image photo.jpg

… (full content is in the download package)