Works with Paperclip
How Xurl fits into a Paperclip company.
Xurl drops into any Paperclip agent that handles this kind of work. Assign it to a specialist inside a pre-configured PaperclipOrg company and the skill becomes available on every heartbeat — no prompt engineering, no tool wiring.
S
SaaS FactoryPaired
Pre-configured AI company — 18 agents, 18 skills, one-time purchase.
$27$59
Explore packSource file
SKILL.md461 linesExpandCollapse
---name: xurldescription: 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) ```bashbrew install --cask xdevplatform/tap/xurl``` ### npm ```bashnpm install -g @xdevplatform/xurl``` ### Shell script ```bashcurl -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 ```bashgo 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: ```bashxurl auth oauth2``` For multiple pre-configured apps, switch between them: ```bashxurl auth default prod-app # set default appxurl auth default prod-app alice # set default app + userxurl --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 postxurl post "Hello world!" # Post with media (upload first, then attach)xurl media upload photo.jpg # → note the media_id from responsexurl post "Check this out" --media-id MEDIA_ID # Multiple mediaxurl 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 mediaxurl reply 1234567890 "Look at this" --media-id MEDIA_ID # Quote a postxurl quote 1234567890 "Adding my thoughts" # Delete your own postxurl delete 1234567890``` ### Reading ```bash# Read a single post (returns author, text, metrics, entities)xurl read 1234567890xurl read https://x.com/user/status/1234567890 # Search recent posts (default 10 results)xurl search "golang"xurl search "from:elonmusk" -n 20xurl search "#buildinpublic lang:en" -n 15``` ### User Info ```bash# Your own profilexurl whoami # Look up any userxurl user elonmuskxurl user @XDevelopers``` ### Timelines & Mentions ```bash# Home timeline (reverse chronological)xurl timelinexurl timeline -n 25 # Your mentionsxurl mentionsxurl mentions -n 20``` ### Engagement ```bash# Like / unlikexurl like 1234567890xurl unlike 1234567890 # Repost / undoxurl repost 1234567890xurl unrepost 1234567890 # Bookmark / removexurl bookmark 1234567890xurl unbookmark 1234567890 # List your bookmarks / likesxurl bookmarks -n 20xurl likes -n 20``` ### Social Graph ```bash# Follow / unfollowxurl follow @XDevelopersxurl unfollow @XDevelopers # List who you follow / your followersxurl following -n 50xurl followers -n 50 # List another user's following/followersxurl following --of elonmusk -n 20xurl followers --of elonmusk -n 20 # Block / unblockxurl block @spammerxurl unblock @spammer # Mute / unmutexurl mute @annoyingxurl unmute @annoying``` ### Direct Messages ```bash# Send a DMxurl dm @someuser "Hey, saw your post!" # List recent DM eventsxurl dmsxurl dms -n 25``` ### Media Upload ```bash# Upload a file (auto‑detects type for images/videos)xurl media upload photo.jpgxurl media upload video.mp4 # Specify type and category explicitlyxurl media upload --media-type image/jpeg --category tweet_image photo.jpg # Check processing status (videos need server‑side processing)xurl media status MEDIA_IDxurl media status --wait MEDIA_ID # poll until done # Full workflow: upload then postxurl media upload meme.png # response includes media idxurl 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 bodyxurl -X POST /2/tweets -d '{"text":"Hello world!"}' # PUT, PATCH, DELETExurl -X DELETE /2/tweets/1234567890 # Custom headersxurl -H "Content-Type: application/json" /2/some/endpoint # Force streaming modexurl -s /2/tweets/search/stream # Full URLs also workxurl 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`: ```bashxurl -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 imagexurl media upload photo.jpg# 2. Copy the media_id from the response, then postxurl post "Check out this photo!" --media-id MEDIA_ID``` ### Reply to a conversation ```bash# 1. Read the post to understand contextxurl read https://x.com/user/status/1234567890# 2. Replyxurl reply 1234567890 "Here are my thoughts..."``` ### Search and engage ```bash# 1. Search for relevant postsxurl search "topic of interest" -n 10# 2. Like an interesting onexurl like POST_ID_FROM_RESULTS# 3. Reply to itxurl reply POST_ID_FROM_RESULTS "Great point!"``` ### Check your activity ```bash# See who you arexurl whoami# Check your mentionsxurl mentions -n 20# Check your timelinexurl 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 appxurl auth default prodxurl auth oauth2 # authenticates on prod app xurl auth default stagingxurl auth oauth2 # authenticates on staging app # Switch between themxurl auth default prod alice # prod app, alice userxurl --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.