— name: xurl description: A CLI tool for making authenticated requests to the X (Twitter) API. Use this skill when you need to post tweets, reply, quote, search, read posts, manage followers, send DMs, upload media, or interact with any X API v2 endpoint. 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 — 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) “`bash brew install –cask xdevplatform/tap/xurl “` ### npm “`bash npm install -g @xdevplatform/xurl “` ### Shell script “`bash 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 “`bash 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: “`bash xurl auth oauth2 “` For multiple pre-configured apps, switch between them: “`bash 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 “` ### 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 “`bash # Simple post xurl post "Hello world!" # Post with media (upload first, then attach) xurl media upload photo.jpg # → note the media_id from response xurl post "Check this out" –media-id MEDIA_ID # Multiple media xurl post "Thread pics" –media-id 111 –media-id 222 # Reply to a post (by ID or URL) xurl reply 1234567890 "Great point!" xurl reply https://x.com/user/status/1234567890 "Agreed!" # Reply with media xurl reply 1234567890 "Look at this" –media-id MEDIA_ID # Quote a post xurl quote 1234567890 "Adding my thoughts" # Delete your own post xurl delete 1234567890 “` ### Reading “`bash # Read a single post (returns author, text, metrics, entities) xurl read 1234567890 xurl read https://x.com/user/status/1234567890 # Search recent posts (default 10 results) xurl search "golang" xurl search "from:elonmusk" -n 20 xurl search "#buildinpublic lang:en" -n 15 “` ### User Info “`bash # Your own profile xurl whoami # Look up any user xurl user elonmusk xurl user @XDevelopers “` ### Timelines & Mentions “`bash # Home timeline (reverse chronological) xurl timeline xurl timeline -n 25 # Your mentions xurl mentions xurl mentions -n 20 “` ### Engagement “`bash # Like / unlike xurl like 1234567890 xurl unlike 1234567890 # Repost / undo xurl repost 1234567890 xurl unrepost 1234567890 # Bookmark / remove xurl bookmark 1234567890 xurl unbookmark 1234567890 # List your bookmarks / likes xurl bookmarks -n 20 xurl likes -n 20 “` ### Social Graph “`bash # Follow / unfollow xurl follow @XDevelopers xurl unfollow @XDevelopers # List who you follow / your followers xurl following -n 50 xurl followers -n 50 # List another user's following/followers xurl following –of elonmusk -n 20 xurl followers –of elonmusk -n 20 # Block / unblock xurl block @spammer xurl unblock @spammer # Mute / unmute xurl mute @annoying xurl unmute @annoying “` ### Direct Messages “`bash # Send a DM xurl dm @someuser "Hey, saw your post!" # List recent DM events xurl dms xurl dms -n 25 “` ### Media Upload “`bash # Upload a file (auto‑detects type for images/videos) xurl media upload photo.jpg xurl media upload video.mp4 # Specify type and category explicitly xurl media upload –media-type image/jpeg –category tweet_image photo.jpg # Check processing status (videos need server‑side processing) xurl media status MEDIA_ID xurl media status –wait MEDIA_ID # poll until done # Full workflow: upload then post xurl media upload meme.png # response includes media id 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: “`bash # GET request (default) xurl /2/users/me # POST with JSON body xurl -X POST /2/tweets -d '{"text":"Hello world!"}' # PUT, PATCH, DELETE xurl -X DELETE /2/tweets/1234567890 # Custom headers xurl -H "Content-Type: application/json" /2/some/endpoint # Force streaming mode xurl -s /2/tweets/search/stream # Full URLs also work 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`: “`bash 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: “`json { "data": { "id": "1234567890", "text": "Hello world!" } } “` Errors are also returned as JSON: “`json { "errors": [ { "message": "Not authorized", "code": 403 } ] } “` — ## Common Workflows ### Post with an image “`bash # 1. Upload the image xurl media upload photo.jpg # 2. Copy the media_id from the response, then post xurl post "Check out this photo!" –media-id MEDIA_ID “` ### Reply to a conversation “`bash # 1. Read the post to understand context xurl read https://x.com/user/status/1234567890 # 2. Reply xurl reply 1234567890 "Here are my thoughts…" “` ### Search and engage “`bash # 1. Search for relevant posts xurl search "topic of interest" -n 10 # 2. Like an interesting one xurl like POST_ID_FROM_RESULTS # 3. Reply to it xurl reply POST_ID_FROM_RESULTS "Great point!" “` ### Check your activity “`bash # See who you are xurl whoami # Check your mentions xurl mentions -n 20 # Check your timeline xurl timeline -n 20 “` ### Set up multiple apps “`bash # App credentials must already be configured manually outside agent/LLM context. # Authenticate users on each pre-configured app xurl auth default prod xurl auth oauth2 # authenticates on prod app xurl auth default staging xurl auth oauth2 # authenticates on staging app # Switch between them xurl auth default prod alice # prod app, alice user xurl –app staging /2/users/me # one-off request against staging “` — ## Error Handling – Non‑zero exit code on any error. – API errors are printed as JSON to stdout (so you can still parse them). – Auth errors suggest re‑running `xurl auth oauth2` or checking your tokens. – If a command requires your user ID (like, repost, bookmark, follow, etc.), xurl will automatically fetch it via `/2/users/me`. If that fails, you'll see an auth error. — ## Notes – **Rate limits:** The X API enforces rate limits per endpoint. If you get a 429 error, wait and retry. Write endpoints (post, reply, like, repost) have stricter limits than read endpoints. – **Scopes:** OAuth 2.0 tokens are requested with broad scopes. If you get a 403 on a specific action, your token may lack the required scope — re‑run `xurl auth oauth2` to get a fresh token. – **Token refresh:** OAuth 2.0 tokens auto‑refresh when expired. No manual intervention needed. – **Multiple apps:** Each app has its own isolated credentials and tokens. Configure credentials manually outside agent/LLM context, then switch with `xurl auth default` or `–app`. – **Multiple accounts:** You can authenticate multiple OAuth 2.0 accounts per app and switch between them with `–username` / `-u` or set a default with `xurl auth default APP USER`. – **Default user:** When no `-u` flag is given, xurl uses the default user for the active app (set via `xurl auth default`). If no default user is set, it uses the first available token. – **Token storage:** `~/.xurl` is YAML. Each app stores its own credentials and tokens. Never read or send this file to LLM context.