xurl — Agent Skill Reference
xurl is a CLI tool for the X API. It supports both shortcut commands (human/agent‑friendly one‑liners) and raw curl‑style access to any v2 endpoint. All commands return JSON to stdout.
Installation
Homebrew (macOS)
brew install --cask xdevplatform/tap/xurl
npm
npm install -g @xdevplatform/xurl
Shell script
curl -fsSL https://raw.githubusercontent.com/xdevplatform/xurl/main/install.sh | bash
Installs to ~/.local/bin. If it's not in your PATH, the script will tell you what to add.
Go
go install github.com/xdevplatform/xurl@latest
Prerequisites
This skill requires the xurl CLI utility: https://github.com/xdevplatform/xurl.
Before using any command you must be authenticated. Run xurl auth status to check.
Secret Safety (Mandatory)
- Never read, print, parse, summarize, upload, or send
~/.xurl (or copies of it) to the LLM context.
- Never ask the user to paste credentials/tokens into chat.
- The user must fill
~/.xurl with required secrets manually on their own machine.
- Do not recommend or execute auth commands with inline secrets in agent/LLM sessions.
- Warn that using CLI secret options in agent sessions can leak credentials (prompt/context, logs, shell history).
- Never use
--verbose / -v in agent/LLM sessions; it can expose sensitive headers/tokens in output.
- Sensitive flags that must never be used in agent commands:
--bearer-token, --consumer-key, --consumer-secret, --access-token, --token-secret, --client-id, --client-secret.
- To verify whether at least one app with credentials is already registered, run:
xurl auth status.
Register an app (recommended)
App credential registration must be done manually by the user outside the agent/LLM session.
After credentials are registered, authenticate with:
xurl auth oauth2
For multiple pre-configured apps, switch between them:
xurl auth default prod-app
xurl auth default prod-app alice
xurl --app dev-app /2/users/me
Other auth methods
Examples with inline secret flags are intentionally omitted. If OAuth1 or app-only auth is needed, the user must run those commands manually outside agent/LLM context.
Tokens are persisted to ~/.xurl in YAML format. Each app has its own isolated tokens. Do not read this file through the agent/LLM. Once authenticated, every command below will auto‑attach the right Authorization header.
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 |
xurl like POST_ID |
| Unlike |
xurl unlike POST_ID |
| Repost |
xurl repost POST_ID |
| Undo repost |
xurl unrepost POST_ID |
| Bookmark |
xurl bookmark POST_ID |
| Remove bookmark |
xurl unbookmark POST_ID |
| List bookmarks |
xurl bookmarks -n 10 |
| List likes |
xurl likes -n 10 |
| Follow |
xurl follow @handle |
| Unfollow |
xurl unfollow @handle |
| List following |
xurl following -n 20 |
| List followers |
xurl followers -n 20 |
| Block |
xurl block @handle |
| Unblock |
xurl unblock @handle |
| Mute |
xurl mute @handle |
| Unmute |
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 |
| App Management |
|
| Register app |
Manual, outside agent (do not pass secrets via agent) |
| List apps |
xurl auth apps list |
| Update app creds |
Manual, outside agent (do not pass secrets via agent) |
| Remove app |
xurl auth apps remove NAME |
| Set default (interactive) |
xurl auth default |
| Set default (command) |
xurl auth default APP_NAME [USERNAME] |
| Use app per-request |
xurl --app NAME /2/users/me |
| Auth status |
xurl auth status |
Post IDs vs URLs: Anywhere POST_ID appears above you can also paste a full post URL (e.g. https://x.com/user/status/1234567890) — xurl extracts the ID automatically.
Usernames: Leading @ is optional. @elonmusk and elonmusk both work.
Command Details
Posting
xurl post "Hello world!"
xurl media upload photo.jpg
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
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
User Info
xurl whoami
xurl user elonmusk
xurl user @XDevelopers
Timelines & Mentions
xurl timeline
xurl timeline -n 25
xurl mentions
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
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
xurl dms -n 25
Media Upload
xurl media upload photo.jpg
xurl media upload video.mp4
xurl media upload --media-type image/jpeg --category tweet_image photo.jpg
xurl media status MEDIA_ID
xurl media status --wait MEDIA_ID
xurl media upload meme.png
xurl post "lol" --media-id MEDIA_ID
Global Flags
These flags work on every command:
| Flag |
Short |
Description |
--app |
|
Use a specific registered app for this request (overrides default) |
--auth |
|
Force auth type: oauth1, oauth2, or app |
--username |
-u |
Which OAuth2 account to use (if you have multiple) |
--verbose |
-v |
Forbidden in agent/LLM sessions (can leak auth headers/tokens) |
--trace |
-t |
Add X-B3-Flags: 1 trace header |
Raw API Access
The shortcut commands cover the most common operations. For anything else, use xurl's raw curl‑style mode — it works with any X API v2 endpoint:
xurl /2/users/me
xurl -X POST /2/tweets -d '{"text":"Hello world!"}'
xurl -X DELETE /2/tweets/1234567890
xurl -H "Content-Type: application/json" /2/some/endpoint
xurl -s /2/tweets/search/stream
xurl https://api.x.com/2/users/me
Streaming
Streaming endpoints are auto‑detected. Known streaming endpoints include:
/2/tweets/search/stream/2/tweets/sample/stream/2/tweets/sample10/stream
You can force streaming on any endpoint with -s:
xurl -s /2/some/endpoint
Output Format
All commands return JSON to stdout, pretty‑printed with syntax highlighting. The output structure matches the X API v2 response format. A typical response looks like:
{
"data": {
"id": "1234567890",
"text": "Hello world!"
}
}
Errors are also returned as JSON:
{
"errors": [
{
"message": "Not authorized",
"code": 403
}
]
}
Common Workflows
Post with an image
xurl media upload photo.jpg
xurl post "Check out this photo!" --media-id MEDIA_ID
Reply to a conversation
xurl read https://x.com/user/status/1234567890
xurl reply 1234567890 "Here are my thoughts..."
Search and engage
xurl search "topic of interest" -n 10
xurl like POST_ID_FROM_RESULTS
xurl reply POST_ID_FROM_RESULTS
