xurl
steipete/clawdis
CLI for authenticated X (Twitter) posts, replies, searches, DMs, media uploads, and raw v2 API calls.
What is xurl?
xurl is a command-line tool for interacting with the X API. Use it to post, reply, search, manage followers, upload media, send DMs, and make raw API calls—all with built-in authentication and secret safety.
- Post, reply, quote, and delete X posts
- Search posts and read timelines, mentions, and user profiles
- Send and receive direct messages
- Upload images and videos with status tracking
- Manage followers, following, blocks, and mutes
- Like, repost, and bookmark posts
How to install xurl
npx skills add https://github.com/steipete/clawdis --skill xurl- xurl CLI installed (via brew or npm)
- X API credentials configured in ~/.xurl
- Valid X API app with appropriate scopes
How to use xurl
- 1.Install xurl via brew (xdevplatform/tap/xurl) or npm (@xdevplatform/xurl)
- 2.Run `xurl auth status` to verify your credentials are set up
- 3.Use shortcut commands like `xurl post "message"` for common tasks
- 4.For advanced operations, use raw mode: `xurl /2/endpoint` or `xurl -X POST /2/endpoint -d '{...}'`
- 5.Check `xurl auth apps list` to manage multiple app credentials if needed
Use cases
- Automate posting updates or alerts to X from your agent
- Search for mentions or trending topics and process results
- Upload media and post with captions programmatically
- Send DMs to users as part of a workflow
- Query user profiles and timelines for data collection
- Developers building X integrations
- Agents automating social media workflows
- Researchers collecting X data
- Teams managing multi-account X presence
xurl FAQ
Never read, print, or inspect ~/.xurl. Never ask users to paste tokens into chat. Use `xurl auth status` to check auth without exposing secrets. Avoid --verbose in agent sessions as it can expose auth headers.
Check your auth status with `xurl auth status`. Verify your app has the correct scopes and that your credentials are valid. You may need to re-authenticate or switch apps with `xurl --app APP_NAME`.
Use `xurl media upload file.jpg` or `xurl media upload video.mp4`. Videos may need processing time; check status with `xurl media status MEDIA_ID`. Then post with `xurl post "caption" --media-id MEDIA_ID`.
Yes. Use raw mode with `xurl /2/endpoint` for GET requests or `xurl -X POST /2/endpoint -d '{...}'` for POST. Keep complex JSON payloads in temp files.
If you receive a 429 error, you are rate limited. Back off and retry after waiting. Check X API rate limit documentation for endpoint-specific limits.
Full instructions (SKILL.md)
Source of truth, from steipete/clawdis.
name: xurl description: "xurl CLI for authenticated X posts, replies, reads/search, DMs, media upload, followers, auth status, or raw v2 API calls." metadata: { "openclaw": { "emoji": "🐦", "requires": { "bins": ["xurl"] }, "install": [ { "id": "brew", "kind": "brew", "formula": "xdevplatform/tap/xurl", "bins": ["xurl"], "label": "Install xurl (brew)", }, { "id": "npm", "kind": "npm", "package": "@xdevplatform/xurl", "bins": ["xurl"], "label": "Install xurl (npm)", }, ], }, }
xurl
Use xurl for X API work. Shortcut commands return JSON; raw mode works for any v2 endpoint.
Secret safety
- Never read, print, summarize, upload, or inspect
~/.xurl. - Never ask user to paste tokens/secrets into chat.
- Do not run auth commands with inline secrets.
- Do not use
--verbosein agent sessions; it can expose auth headers. - Check auth with
xurl auth status.
Common shortcuts
xurl post "Hello world!"
xurl reply POST_ID "Nice."
xurl quote POST_ID "My take"
xurl delete POST_ID
xurl read POST_ID
xurl search "query" -n 20
xurl whoami
xurl user @handle
xurl timeline -n 20
xurl mentions -n 10
xurl like POST_ID
xurl unlike POST_ID
xurl repost POST_ID
xurl unrepost POST_ID
xurl bookmark POST_ID
xurl unbookmark POST_ID
xurl followers -n 20
xurl following -n 20
xurl follow @handle
xurl unfollow @handle
xurl block @handle
xurl unblock @handle
xurl mute @handle
xurl unmute @handle
xurl dm @handle "message"
xurl dms -n 10
POST_ID can be a full https://x.com/<user>/status/<id> URL.
Media
xurl media upload image.jpg
xurl media upload clip.mp4
xurl media status MEDIA_ID
xurl post "caption" --media-id MEDIA_ID
Videos may need processing; poll media status.
Auth/app management
xurl auth status
xurl auth apps list
xurl auth default
xurl auth default APP_NAME USERNAME
xurl auth apps remove APP_NAME
Per request:
xurl --app APP_NAME /2/users/me
xurl --auth oauth2 /2/users/me
Raw API
xurl /2/users/me
xurl -X POST /2/tweets -d '{"text":"Hello world!"}'
xurl '/2/tweets/search/recent?query=openclaw&max_results=10'
Use raw mode when shortcuts do not cover the endpoint. Keep payloads in temp files for complex JSON.
Output and errors
- JSON stdout on success.
- Non-zero exit on API/auth/network errors.
- 401/403: auth, scope, or app mismatch; check
xurl auth status. - 429: rate limited; back off.
- Media upload failures: check file type/size and media processing status.
Related skills
More from steipete/clawdis and the wider catalog.
1password
Set up and use 1Password CLI for sign-in, desktop integration, and reading or injecting secrets.
apple-notes
Create, view, edit, delete, search, move, and export Apple Notes from the terminal on macOS.
apple-reminders
Manage Apple Reminders from the terminal with remindctl.
bear-notes
Create, search, and manage Bear notes via grizzly CLI on macOS.
beads
>
developing-with-streamlit
Complete Streamlit development toolkit with version-matched reference docs and support for apps, styling, custom components, and deployment.