lidge-jun xurl — Agent Skill Reference
xurl is a CLI for the X API. Supports shortcut commands (one-liners) and raw curl-style access to any v2 endpoint. All output is JSON to stdout.
Installation
# Homebrew (macOS)
brew install --cask xdevplatform/tap/xurl
# npm
npm install -g @xdevplatform/xurl
# Shell script (installs to ~/.local/bin)
curl -fsSL https://raw.githubusercontent.com/xdevplatform/xurl/main/install.sh | bash
# Go
go install github.com/xdevplatform/xurl@latest
Authentication
Run xurl auth status to check current auth state.
Secret Safety
- Never read, print, or send
~/.xurlto LLM context (contains tokens). - Never pass credentials via agent commands — user fills
~/.xurlmanually. - Never use
--verbose/-vin agent sessions (exposes auth headers). - Forbidden flags in agent commands:
--bearer-token,--consumer-key,--consumer-secret,--access-token,--token-secret,--client-id,--client-secret.
Setup
App credential registration must be done by the user outside the agent session. After registration:
xurl auth oauth2 # authenticate
xurl auth default prod-app # set default app
xurl auth default prod-app alice # set default app + user
xurl --app dev-app /2/users/me # one-off override
Tokens persist to ~/.xurl in YAML (per-app isolated). OAuth 2.0 tokens auto-refresh.
Quick Reference
| Action | Command |
|---|---|
| Post | xurl post "Hello world!" |
| Reply | xurl reply POST_ID "Nice post!" |
| Quote | xurl quote POST_ID "My take" |
| Delete | xurl delete POST_ID |
| Read | xurl read POST_ID |
| Search | xurl search "QUERY" -n 10 |
| Who am I | xurl whoami |
| User lookup | xurl user @handle |
| 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 | xurl bookmarks -n 10 |
| List likes | 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 |
| App Management | |
| List apps | xurl auth apps list |
| Remove app | xurl auth apps remove NAME |
| Set default | xurl auth default APP_NAME [USERNAME] |
| Per-request app | xurl --app NAME /2/users/me |
| Auth status | xurl auth status |
POST_IDaccepts full URLs too (e.g.https://x.com/user/status/123) — xurl extracts the ID.
Leading
@is optional for usernames.
Media Workflow
Upload first, then attach to post:
xurl media upload photo.jpg # note the media_id
xurl post "Check this out" --media-id MEDIA_ID
# Multiple media
xurl post "Thread pics" --media-id 111 --media-id 222
# Video: poll until processing completes
xurl media upload video.mp4
xurl media status --wait MEDIA_ID
xurl post "Watch this" --media-id MEDIA_ID
Social Graph Extras
# Another user's following/followers
xurl following --of elonmusk -n 20
xurl followers --of elonmusk -n 20
Global Flags
| Flag | Short | Description |
|---|---|---|
--app |
Use a specific registered app (overrides default) | |
--auth |
Force auth type: oauth1, oauth2, or app |
|
--username |
-u |
Which OAuth2 account to use |
--verbose |
-v |
Forbidden in agent sessions (leaks auth headers) |
--trace |
-t |
Add X-B3-Flags: 1 trace header |
Raw API Access
For endpoints not covered by shortcuts:
xurl /2/users/me # GET (default)
xurl -X POST /2/tweets -d '{"text":"Hello!"}' # POST with JSON
xurl -X DELETE /2/tweets/1234567890 # DELETE
xurl -H "Content-Type: application/json" /2/endpoint # custom headers
xurl -s /2/tweets/search/stream # force streaming
xurl https://api.x.com/2/users/me # full URLs work
Streaming
Auto-detected for known endpoints (/2/tweets/search/stream, /2/tweets/sample/stream, /2/tweets/sample10/stream). Force with -s.
Error Handling
- Non-zero exit code on errors; API errors returned as JSON to stdout.
- Auth errors suggest re-running
xurl auth oauth2. - Commands needing your user ID (like, repost, bookmark, follow) auto-fetch via
/2/users/me.
Notes
- Rate limits: 429 → wait and retry. Write endpoints have stricter limits than reads.
- Scopes: 403 on an action may mean the token lacks a required scope — re-run
xurl auth oauth2. - Multiple accounts: Authenticate multiple OAuth2 accounts per app; switch with
-uorxurl auth default APP USER.