Skip to content
Back to search

xurl

SkillWorks with Claude CodeGitHub

A curl-like 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, send or read end-to-end encrypted XChat messages, upload media, or interact with any X API v2 endpoint. Supports multiple apps, OAuth 2.0, OAuth 1.0a, and app-only auth.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/xdevplatform--xurl/badge.svg)](/listings/xdevplatform--xurl)

HTML

<a href="/listings/xdevplatform--xurl"><img src="/api/listings/xdevplatform--xurl/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

Homebrew (macOS)

brew install --cask xdevplatform/tap/xurl

npm

npm install -g @xdevplatform/xurl

Shell script (no sudo required)

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

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 494 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. ---
  2. name: xurl
  3. description: A curl-like 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, send or read end-to-end encrypted XChat messages, upload media, or interact with any X API v2 endpoint. Supports multiple apps, OAuth 2.0, OAuth 1.0a, and app-only auth.
  4. ---
  5. # xurl — Agent Skill Reference
  6. `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.
  7. ---
  8. ## Prerequisites
  9. This skill requires the `xurl` CLI utility: <https://github.com/xdevplatform/xurl>.
  10. Before using any command you must be authenticated. Run `xurl auth status` to check.
  11. ### Secret Safety (Mandatory)
  12. - Never read, print, parse, summarize, upload, or send anything under `~/.xurl/` (or copies of it) to the LLM context.
  13. - `~/.xurl/keys.yml` contains XChat **private encryption keys** — the strictest no-read rule applies.
  14. - Never pass `--pin` inline in agent/LLM sessions (`xurl chat keys restore --pin ...` leaks the recovery PIN to context and shell history). Run `xurl chat keys restore` without the flag so the PIN is prompted without echo, or have the user run it manually.
  15. - Never ask the user to paste credentials/tokens into chat.
  16. - The user must fill `~/.xurl/auth.yml` with required secrets manually on their own machine.
  17. - Do not recommend or execute auth commands with inline secrets in agent/LLM sessions.
  18. - Warn that using CLI secret options in agent sessions can leak credentials (prompt/context, logs, shell history).
  19. - Never use `--verbose` / `-v` in agent/LLM sessions; it can expose sensitive headers/tokens in output.
  20. - Never run `xurl token` in agent/LLM sessions: it prints a live OAuth2 access token to stdout, which is a credential and must not enter the LLM context.
  21. - `xurl mcp` is for configuring an MCP client (it bridges stdio↔HTTP and injects the bearer token); it is not something to invoke directly from an agent/LLM session.
  22. - Sensitive flags that must never be used in agent commands: `--bearer-token`, `--consumer-key`, `--consumer-secret`, `--access-token`, `--token-secret`, `--client-id`, `--client-secret`.
  23. - To verify whether at least one app with credentials is already registered, run: `xurl auth status`.
  24. ### Register an app (recommended)
  25. App credential registration must be done manually by the user outside the agent/LLM session.
  26. After credentials are registered, authenticate against the app that holds those credentials:
  27. ```bash
  28. xurl auth oauth2 --app APP_NAME
  29. ```
  30. You can also run `xurl auth default APP_NAME` first and then use `xurl auth oauth2`.
  31. On a remote/headless machine (no reachable browser callback), add `--headless`: `xurl auth oauth2 --app APP_NAME --headless` prints the authorization URL and reads the pasted redirect URL (or code) back, so no localhost callback is needed.
  32. For multiple pre-configured apps, switch between them:
  33. ```bash
  34. xurl auth default prod-app # set default app
  35. xurl auth default prod-app alice # set default app + user
  36. xurl --app dev-app /2/users/me # one-off override
  37. xurl auth apps redirect-uri get prod-app
  38. xurl auth apps redirect-uri set prod-app http://localhost:8080/callback
  39. ```
  40. ### Other auth methods
  41. 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.
  42. Tokens are persisted to `~/.xurl/auth.yml` in YAML format (a legacy single-file `~/.xurl` is migrated automatically). Each app has its own isolated tokens and may also store a `redirect_uri`. `REDIRECT_URI` in the environment still takes precedence over the stored app value. Do not read this file (or anything under `~/.xurl/`) through the agent/LLM. Once authenticated, every command below will auto‑attach the right `Authorization` header.
  43. ---
  44. ## Quick Reference
  45. | Action | Command |
  46. |---|---|
  47. | Post | `xurl post "Hello world!"` |
  48. | Reply | `xurl reply POST_ID "Nice post!"` |
  49. | Quote | `xurl quote POST_ID "My take"` |
  50. | Delete a post | `xurl delete POST_ID` |
  51. | Read a post | `xurl read POST_ID` |
  52. | Search posts | `xurl search "QUERY" -n 10` |
  53. | Who am I | `xurl whoami` |
  54. | Look up a user | `xurl user @handle` |
  55. | List a user's posts | `xurl posts @handle -n 10` |
  56. | Home timeline | `xurl timeline -n 20` |
  57. | Mentions | `xurl mentions -n 10` |
  58. | Like | `xurl like POST_ID` |
  59. | Unlike | `xurl unlike POST_ID` |
  60. | Repost | `xurl repost POST_ID` |
  61. | Undo repost | `xurl unrepost POST_ID` |
  62. | Bookmark | `xurl bookmark POST_ID` |
  63. | Remove bookmark | `xurl unbookmark POST_ID` |
  64. | List bookmarks | `xurl bookmarks -n 10` |
  65. | List likes | `xurl likes -n 10` |
  66. | Follow | `xurl follow @handle` |
  67. | Unfollow | `xurl unfollow @handle` |
  68. | List following | `xurl following -n 20` |
  69. | List followers | `xurl followers -n 20` |
  70. | Block | `xurl block @handle` |
  71. | Unblock | `xurl unblock @handle` |
  72. | Mute | `xurl mute @handle` |
  73. | Unmute | `xurl unmute @handle` |
  74. | Send DM | `xurl dm @handle "message"` |
  75. | List DMs | `xurl dms -n 10` |
  76. | Upload media | `xurl media upload path/to/file.mp4` |
  77. | Media status | `xurl media status MEDIA_ID` |
  78. | **Encrypted Chat (XChat)** | |
  79. | Chat key status | `xurl chat keys status` |
  80. | Restore chat keys | `xurl chat keys restore` (PIN prompted; never pass `--pin` in agent sessions) |
  81. | Import chat keys | `xurl chat keys import` (blob prompted; avoid passing it as an argument) |
  82. | List chat inbox | `xurl chat conversations` |
  83. | Read a conversation | `xurl chat read @handle -n 50` |
  84. | Send encrypted message | `xurl chat send @handle "message"` |
  85. | Listen for new messages | `xurl chat listen @handle` |
  86. | Rotate a conversation key | `xurl chat rotate CONV --yes` (write op — see notes) |
  87. | Send with an attachment | `xurl chat send CONV "text" --file path/to/img.png` |
  88. | Reply to a message | `xurl chat send CONV "text" --reply-to SEQUENCE_ID` |
  89. | Download an attachment | `xurl chat download CONV MEDIA_HASH_KEY -o out.png` |
  90. | Add group members | `xurl chat add-members GROUP @user --yes` (write op) |
  91. | Mark read (explicit) | `xurl chat mark-read CONV` |
  92. | Typing indicator (explicit) | `xurl chat typing CONV` |
  93. | **App Management** | |
  94. | Register app | Manual, outside agent (do not pass secrets via agent) |
  95. | List apps | `xurl auth apps list` |
  96. | Update app config | Manual, outside agent (do not pass secrets via agent) |
  97. | View app redirect URI | `xurl auth apps redirect-uri get [NAME]` |
  98. | Set app redirect URI | `xurl auth apps redirect-uri set NAME URI` |
  99. | Remove app | `xurl auth apps remove NAME` |
  100. | Set default (interactive) | `xurl auth default` |
  101. | Set default (command) | `xurl auth default APP_NAME [USERNAME]` |
  102. | Use app per-request | `xurl --app NAME /2/users/me` |
  103. | Auth status | `xurl auth status` |
  104. > **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.
  105. > **Usernames:** Leading `@` is optional. `@elonmusk` and `elonmusk` both work.
  106. ---
  107. ## Command Details
  108. ### Posting
  109. ```bash
  110. # Simple post
  111. xurl post "Hello world!"
  112. # Post with media (upload first, then attach)
  113. xurl media upload photo.jpg # → note the media_id from response
  114. xurl post "Check this out" --media-id MEDIA_ID
  115. # Multiple media
  116. xurl post "Thread pics" --media-id 111 --media-id 222
  117. # Reply to a post (by ID or URL)
  118. xurl reply 1234567890 "Great point!"
  119. xurl reply https://x.com/user/status/1234567890 "Agreed!"
  120. # Reply with media
  121. xurl reply 1234567890 "Look at this" --media-id MEDIA_ID
  122. # Quote a post
  123. xurl quote 1234567890 "Adding my thoughts"
  124. # Delete your own post
  125. xurl delete 1234567890
  126. ```
  127. ### Reading
  128. ```bash
  129. # Read a single post (returns author, text, metrics, entities)
  130. xurl read 1234567890
  131. xurl read https://x.com/user/status/1234567890
  132. # Search recent posts (default 10 results)
  133. xurl search "golang"
  134. xurl search "from:elonmusk" -n 20
  135. xurl search "#buildinpublic lang:en" -n 15
  136. ```
  137. ### User Info
  138. ```bash
  139. # Your own profile
  140. xurl whoami
  141. # Look up any user
  142. xurl user elonmusk
  143. xurl user @XDevelopers
  144. # List a user's recent posts (by @username)
  145. xurl posts elonmusk
  146. xurl posts @XDevelopers -n 25
  147. ```
  148. ### Timelines & Mentions
  149. ```bash
  150. # Home timeline (reverse chronological)
  151. xurl timeline
  152. xurl timeline -n 25
  153. # Your mentions
  154. xurl mentions
  155. xurl mentions -n 20
  156. ```
  157. ### Engagement
  158. ```bash
  159. # Like / unlike
  160. xurl like 1234567890
  161. xurl unlike 1234567890
  162. # Repost / undo
  163. xurl repost 1234567890
  164. xurl unrepost 1234567890
  165. # Bookmark / remove
  166. xurl bookmark 1234567890
  167. xurl unbookmark 1234567890
  168. # List your bookmarks / likes
  169. xurl bookmarks -n 20
  170. xurl likes -n 20
  171. ```
  172. ### Social Graph
  173. ```bash
  174. # Follow / unfollow
  175. xurl follow @XDevelopers
  176. xurl unfollow @XDevelopers
  177. # List who you follow / your followers
  178. xurl following -n 50
  179. xurl followers -n 50
  180. # List another user's following/followers
  181. xurl following --of elonmusk -n 20
  182. xurl followers --of elonmusk -n 20
  183. # Block / unblock
  184. xurl block @spammer
  185. xurl unblock @spammer
  186. # Mute / unmute
  187. xurl mute @annoying
  188. xurl unmute @annoying
  189. ```
  190. ### Direct Messages
  191. ```bash
  192. # Send a DM
  193. xurl dm @someuser "Hey, saw your post!"
  194. # List recent DM events
  195. xurl dms
  196. xurl dms -n 25
  197. ```
  198. ### Encrypted Chat (XChat)
  199. `xurl chat` is an end-to-end encrypted XChat client: encryption and decryption happen locally via the chat-xdk crypto library, so the server only sees ciphertext. Requires OAuth2 user auth with `dm.read` + `dm.write` scopes, and is available on macOS (Intel/Apple Silicon) and Linux amd64 — release binaries include it there; elsewhere (Windows, Linux arm64/i386) `xurl chat` prints a stub that says so.
  200. **Keys come from another XChat client** — xurl never generates or registers encryption keys. The account must already have keys (e.g. from the X app); bring them to this machine once with `restore` (Juicebox PIN recovery) or `import` (an exported key blob). Private keys are stored in `~/.xurl/keys.yml` (mode 600) — never read that file into LLM context.
  201. A conversation is addressed by `@username`, a bare user id, or a conversation id (1:1 ids look like `123-456`; group ids look like `g123`). Every command accepts `-u USERNAME` to act as a specific authenticated account.
  202. ```bash
  203. # 1. Keys — one-time setup (xurl never generates/registers keys)
  204. xurl chat keys status # local key presence/fingerprint + registered versions
  205. xurl chat keys restore # recover from Juicebox; prompts for the PIN (no echo)
  206. xurl chat keys import # paste an exported private-key blob (no echo)
  207. # 2. Browse the inbox
  208. xurl chat conversations # pretty list; decrypts group names when keys are present
  209. xurl chat conversations --json # raw JSON
  210. # 3. Read history (oldest first; auto-marks the conversation read)
  211. xurl chat read @someuser
  212. xurl chat read g1234567890 -n 50 # -n = how many events to fetch (max 100)
  213. xurl chat read @someuser --json # decrypted events as JSON (each has id, sequence_id, content)
  214. xurl chat read @someuser --no-mark-read # read without sending a read receipt
  215. # 4. Send (a new 1:1 sets up its key automatically; both sides need keys)
  216. xurl chat send @someuser "hey, encrypted!"
  217. xurl chat send @someuser "look" --file ./photo.png # attach an encrypted file
  218. xurl chat send @someuser "agreed" --reply-to SEQUENCE_ID # threaded reply (id from `read --json`)
  219. # send auto-sends a typing indicator first and marks read after;
  220. # suppress with --no-typing / --no-mark-read
  221. # 5. Attachments — inbound messages show "📎 attachment <media_hash_key>"
  222. xurl chat download @someuser MEDIA_HASH_KEY -o out.png # download + decrypt
  223. # 6. Live tail (poll loop; Ctrl-C to stop; auto-marks new messages read)
  224. xurl chat listen @someuser
  225. xurl chat listen g1234567890 --interval 5
  226. # 7. Read receipts / typing (also happen automatically on read/send)
  227. xurl chat mark-read @someuser # mark read up to the newest message
  228. xurl chat typing @someuser # send a typing indicator
  229. # 8. Group key management (writes visible to all participants)
  230. xurl chat add-members g123 @newuser # add a member (rotates the key; prompts, or --yes)
  231. xurl chat rotate g123 # rotate the conversation key; prompts, or --yes
  232. # Rotate when a key may be exposed, or to grant a member whose keys were
  233. # registered after the last rotation access going forward. Future messages
  234. # only — old history stays readable only to holders of the old key versions.
  235. ```
  236. Notes for agents:
  237. - Messages whose authorship signature cannot be verified are rejected by default and surface as stderr decrypt warnings; unsigned messages that still render carry a red `[unverified]` marker — treat those with suspicion.
  238. - Messages with attachments render a `📎 attachment <media_hash_key>` marker; pass that hash key to `xurl chat download CONV <media_hash_key>` to fetch and decrypt the file. Replies show a `↩` prefix.
  239. - **`read` and `listen` mark the conversation read automatically** (a read receipt visible to other participants); `send` also marks read and sends a typing indicator first. These are writes — pass `--no-mark-read` / `--no-typing` to suppress them (e.g. to read without signaling). The standalone `mark-read` and `typing` commands remain for scripted/explicit use.
  240. - Decrypt warnings for individual events go to stderr and are non-fatal; the rest of the conversation still renders.
  241. - If a command reports missing keys, do not attempt to generate or register any — tell the user to run `xurl chat keys restore` (or `import`) themselves.
  242. - `chat rotate` and `chat add-members` are writes visible to every participant's clients; never run them without explicit user intent, and prefer letting the user confirm the prompt over passing `--yes`.
  243. ### Media Upload
  244. ```bash
  245. # Upload a file (auto‑detects type for images/videos)
  246. xurl media upload photo.jpg
  247. xurl media upload video.mp4
  248. # Specify type and category explicitly
  249. xurl media upload --media-type image/jpeg --category tweet_image photo.jpg
  250. # Check processing status (videos need server‑side processing)
  251. xurl media status MEDIA_ID
  252. xurl media status --wait MEDIA_ID # poll until done
  253. # Full workflow: upload then post
  254. xurl media upload meme.png # response includes media id
  255. xurl post "lol" --media-id MEDIA_ID
  256. ```
  257. ---
  258. ## Global Flags
  259. These flags work on every command:
  260. | Flag | Short | Description |
  261. |---|---|---|
  262. | `--app` | | Use a specific registered app for this request (overrides default) |
  263. | `--auth` | | Force auth type: `oauth1`, `oauth2`, or `app` |
  264. | `--username` | `-u` | Which OAuth2 account to use (if you have multiple) |
  265. | `--verbose` | `-v` | Forbidden in agent/LLM sessions (can leak auth headers/tokens) |
  266. ---
  267. ## Raw API Access
  268. 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:
  269. ```bash
  270. # GET request (default)
  271. xurl /2/users/me
  272. # POST with JSON body
  273. xurl -X POST /2/tweets -d '{"text":"Hello world!"}'
  274. # PUT, PATCH, DELETE
  275. xurl -X DELETE /2/tweets/1234567890
  276. # Custom headers
  277. xurl -H "Content-Type: application/json" /2/some/endpoint
  278. # Force streaming mode
  279. xurl -s /2/tweets/search/stream
  280. # Full URLs also work
  281. xurl https://api.x.com/2/users/me
  282. ```
  283. ---
  284. ## Streaming
  285. Streaming endpoints are auto‑detected. Known streaming endpoints include:
  286. - `/2/tweets/search/stream`
  287. - `/2/tweets/sample/stream`
  288. - `/2/tweets/sample10/stream`
  289. You can force streaming on any endpoint with `-s`:
  290. ```bash
  291. xurl -s /2/some/endpoint
  292. ```
  293. ---
  294. ## Output Format
  295. 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:
  296. ```json
  297. {
  298. "data": {
  299. "id": "1234567890",
  300. "text": "Hello world!"
  301. }
  302. }
  303. ```
  304. Errors are also returned as JSON:
  305. ```json
  306. {
  307. "errors": [
  308. {
  309. "message": "Not authorized",
  310. "code": 403
  311. }
  312. ]
  313. }
  314. ```
  315. ---
  316. ## Common Workflows
  317. ### Post with an image
  318. ```bash
  319. # 1. Upload the image
  320. xurl media upload photo.jpg
  321. # 2. Copy the media_id from the response, then post
  322. xurl post "Check out this photo!" --media-id MEDIA_ID
  323. ```
  324. ### Reply to a conversation
  325. ```bash
  326. # 1. Read the post to understand context
  327. xurl read https://x.com/user/status/1234567890
  328. # 2. Reply
  329. xurl reply 1234567890 "Here are my thoughts..."
  330. ```
  331. ### Search and engage
  332. ```bash
  333. # 1. Search for relevant posts
  334. xurl search "topic of interest" -n 10
  335. # 2. Like an interesting one
  336. xurl like POST_ID_FROM_RESULTS
  337. # 3. Reply to it
  338. xurl reply POST_ID_FROM_RESULTS "Great point!"
  339. ```
  340. ### Check your activity
  341. ```bash
  342. # See who you are
  343. xurl whoami
  344. # Check your mentions
  345. xurl mentions -n 20
  346. # Check your timeline
  347. xurl timeline -n 20
  348. ```
  349. ### Set up multiple apps
  350. ```bash
  351. # App credentials must already be configured manually outside agent/LLM context.
  352. # Authenticate users on each pre-configured app
  353. xurl auth default prod
  354. xurl auth oauth2 # authenticates on prod app
  355. xurl auth default staging
  356. xurl auth oauth2 # authenticates on staging app
  357. # Switch between them
  358. xurl auth default prod alice # prod app, alice user
  359. xurl --app staging /2/users/me # one-off request against staging
  360. ```
  361. ---
  362. ## Error Handling
  363. - Non‑zero exit code on any error.
  364. - API errors are printed as JSON to stdout (so you can still parse them).
  365. - Auth errors suggest re‑running `xurl auth oauth2` or checking your tokens.
  366. - If a command requires your user ID (like, repost, bookmark, follow, etc.), xurl will automatically fetch it via `/2/users/me`. When that endpoint is unreliable, use `--username USERNAME` or authenticate with `xurl auth oauth2 --app APP_NAME USERNAME` so xurl can fall back to username lookup.
  367. - If X returns `client-forbidden` / `client-not-enrolled` after successful auth, check the app’s X developer-console package and environment. In current testing, moving the app to `Pay-per-use` and `Production` fixed `/2/*` read failures without changing local `xurl` auth data.
  368. ---
  369. ## Notes
  370. - **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.
  371. - **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.
  372. - **Token refresh:** OAuth 2.0 tokens auto‑refresh when expired. No manual intervention needed.
  373. - **Multiple apps:** Each app has its own isolated credentials, tokens, and optional stored `redirect_uri`. Configure credentials manually outside agent/LLM context, then switch with `xurl auth default` or `--app`.
  374. - **Redirect URI precedence:** The effective redirect URI resolves from `REDIRECT_URI` in the environment first, then the app's stored `redirect_uri` in `~/.xurl/auth.yml`, then the built-in default.
  375. - **Redirect URI management:** Use `xurl auth apps redirect-uri get [NAME]`, `xurl auth apps redirect-uri set NAME URI`, or `xurl auth apps update NAME --redirect-uri URI` to inspect and manage the stored per-app callback value.
  376. - **X platform enrollment:** A successful OAuth callback does not guarantee `/2/*` reads will work. If you see `client-not-enrolled`, verify the app is in the correct X package/environment. Current confirmed fix: `Apps` -> `Manage apps` -> `Move to package` -> choose `Pay-per-use`, then move the app to `Production`.
  377. - **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`.
  378. - **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.
  379. - **Token storage:** `~/.xurl` is a directory; `~/.xurl/auth.yml` holds each app's credentials and tokens. Never read or send anything under `~/.xurl/` to LLM context.
  380. - **Chat key storage:** `~/.xurl/keys.yml` holds XChat **private encryption keys** per user (mode 600). Losing it means losing the ability to decrypt on this machine (recoverable via `xurl chat keys restore` if a Juicebox PIN backup exists). Never read or send this file to LLM context.
  381. - **Chat key registration:** xurl performs none — no public-key registration and no Juicebox writes. Only keys already registered by another XChat client can be restored or imported; unregistered keys are rejected.
  382. - **Access tokens:** `xurl token` prints a valid (refreshed) OAuth2 access token for the active app to stdout, refreshing and persisting it if expired. It never opens a browser. The output is a secret — use it only in the user's own scripts, never in agent/LLM sessions.
  383. - **MCP bridge:** `xurl mcp [URL]` bridges a stdio MCP client to a remote Streamable HTTP MCP server (default `https://api.x.com/mcp`), injecting `Authorization: Bearer <token>` and refreshing the token automatically. On first run with no cached token it opens the browser for a one-time OAuth2 login using the `CLIENT_ID`/`CLIENT_SECRET` from its environment (the handshake waits for it, so set a generous `startup_timeout_sec`); on a headless host, authenticate out-of-band first with `xurl auth oauth2 --headless`. Configure it in an MCP client via the npm launcher: `{"command":"npx","args":["-y","@xdevplatform/xurl","mcp","https://api.x.com/mcp"],"env":{"CLIENT_ID":"...","CLIENT_SECRET":"..."},"startup_timeout_sec":300}`.
README.md · README · 464 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # xurl - A curl-like CLI Tool for the X API
  2. A command-line tool for interacting with the X (formerly Twitter) API, supporting both OAuth 1.0a and OAuth 2.0 authentication.
  3. ## Features
  4. - **Multi-app support** — register multiple X API apps with separate credentials and tokens
  5. - OAuth 2.0 PKCE flow authentication
  6. - OAuth 1.0a authentication
  7. - Multiple OAuth 2.0 account support per app
  8. - Default app and default user selection (interactive Bubble Tea picker or single command)
  9. - Persistent token storage in YAML (`~/.xurl/auth.yml`), auto-migrates from the legacy single-file layout
  10. - HTTP request customization (headers, methods, body)
  11. - Per-request app override with `--app`
  12. - End-to-end encrypted XChat client (`xurl chat`) built on the official chat-xdk crypto library
  13. ## Installation
  14. ### Homebrew (macOS)
  15. ```bash
  16. brew install --cask xdevplatform/tap/xurl
  17. ```
  18. ### npm
  19. ```bash
  20. npm install -g @xdevplatform/xurl
  21. ```
  22. ### Shell script (no sudo required)
  23. ```bash
  24. curl -fsSL https://raw.githubusercontent.com/xdevplatform/xurl/main/install.sh | bash
  25. ```
  26. Installs to `~/.local/bin`. If it's not in your PATH, the script will tell you what to add.
  27. ### Go
  28. ```bash
  29. go install github.com/xdevplatform/xurl@latest
  30. ```
  31. ## Usage
  32. ### Authentication
  33. You must have a developer account and app to use this tool.
  34. #### Register an app
  35. Register your X API app credentials so they're stored in `~/.xurl/auth.yml` (no env vars needed after this):
  36. ```bash
  37. xurl auth apps add my-app --client-id YOUR_CLIENT_ID --client-secret YOUR_CLIENT_SECRET
  38. ```
  39. If you want the app to keep its own callback configuration in `~/.xurl/auth.yml`, you can store the redirect URI there too:
  40. ```bash
  41. xurl auth apps add my-app --client-id YOUR_CLIENT_ID --client-secret YOUR_CLIENT_SECRET --redirect-uri http://localhost:8080/callback
  42. ```
  43. You can register multiple apps:
  44. ```bash
  45. xurl auth apps add prod-app --client-id PROD_ID --client-secret PROD_SECRET
  46. xurl auth apps add dev-app --client-id DEV_ID --client-secret DEV_SECRET
  47. ```
  48. > **Legacy / env-var flow:** You can also set `CLIENT_ID` and `CLIENT_SECRET` as environment variables. They'll be auto-saved into the active app on first use.
  49. >
  50. > `REDIRECT_URI` now resolves in this order: `REDIRECT_URI` environment variable, then the app's stored `redirect_uri` in `~/.xurl/auth.yml`, then the built-in default `http://localhost:8080/callback`.
  51. #### OAuth 2.0 User-Context
  52. **Note:** For OAuth 2.0 authentication, you must specify the redirect URI in the [X Developer Console](https://console.x.com).
  53. 1. Create an app in the [X Developer Console](https://console.x.com).
  54. 2. In the console, go to `Apps`, open your app, and on the `Keys & Tokens` tab click `Set up` next to `User authentication settings`. If the app is already set up, use the `Settings` button on the app page. Under `App info`, set `Callback URI / Redirect URL` to the same value that `xurl` will use through `REDIRECT_URI`.
  55. The default is `http://localhost:8080/callback`, and `xurl` derives the callback host, port, and path from the effective redirect URI. The effective value is resolved from `REDIRECT_URI`, then the app's stored `redirect_uri`, then the built-in default. When you use `localhost`, `xurl` listens on both `127.0.0.1` and `::1` so browser loopback resolution does not break the callback.
  56. ![Setup](./assets/setup.png)
  57. ![Redirect URI](./assets/callback.png)
  58. 3. Register the app (if you haven't already):
  59. ```bash
  60. xurl auth apps add my-app --client-id YOUR_CLIENT_ID --client-secret YOUR_CLIENT_SECRET
  61. ```
  62. 4. Get your access keys for the registered app:
  63. ```bash
  64. xurl auth oauth2 --app my-app
  65. ```
  66. If you omit `--app`, the token is saved to the current default app. You can also run `xurl auth default my-app` first and then use `xurl auth oauth2`.
  67. **Headless / remote machines.** The default flow opens a browser and waits for a callback on `localhost`, which isn't reachable from a remote server. On those hosts use `--headless`:
  68. ```bash
  69. xurl auth oauth2 --app my-app --headless
  70. ```
  71. xurl prints the authorization URL; open it on any device with a browser, approve, then paste the resulting redirect URL (or just the `code` value from the address bar) back into the prompt. No callback listener is needed — the page failing to load is expected; the code is in the URL.
  72. If X returns a `client-forbidden` / `client-not-enrolled` error even though auth completed successfully, check the app’s package and environment in the X developer console. On current X platform setup, the working fix was:
  73. 1. Go to `Apps` -> `Manage apps`
  74. 2. Open the app
  75. 3. Use `Move to package`
  76. 4. Choose `Pay-per-use`
  77. 5. Move the app to the `Production` environment
  78. Without that enrollment step, `xurl whoami` and other `/2/*` reads can fail even when the OAuth callback and tokens are valid.
  79. If X does not return your username reliably through `/2/users/me`, authenticate with an explicit handle instead:
  80. ```bash
  81. xurl auth oauth2 --app my-app YOUR_USERNAME
  82. ```
  83. That keeps the OAuth2 token associated with the expected username and also gives shortcut commands a fallback when `/2/users/me` is unavailable.
  84. #### App-only authentication (Bearer Token):
  85. ```bash
  86. xurl auth app-only BEARER_TOKEN
  87. cat token.txt | xurl auth app-only - # read from stdin (keeps it out of shell history)
  88. ```
  89. This stores X's app-only Bearer Token (from the developer portal), used at request time with `--auth app`. It's named for the auth *mode* (app-only) rather than the token *scheme* (bearer), since OAuth2 user tokens are also sent as `Authorization: Bearer`.
  90. > Back-compat: `xurl auth app` and `xurl auth bearer` still work as aliases, and `--bearer-token TOKEN` is still accepted.
  91. #### OAuth 1.0a authentication:
  92. ```bash
  93. xurl auth oauth1 --consumer-key KEY --consumer-secret SECRET --access-token TOKEN --token-secret SECRET
  94. ```
  95. ### Multi-App Management
  96. List registered apps:
  97. ```bash
  98. xurl auth apps list
  99. ```
  100. Update credentials on an existing app:
  101. ```bash
  102. xurl auth apps update my-app --client-id NEW_ID --client-secret NEW_SECRET
  103. xurl auth apps update my-app --redirect-uri http://localhost:8080/callback
  104. ```
  105. `REDIRECT_URI` from the environment still overrides the stored app value at runtime, so `auth apps update --redirect-uri` is best for your default per-app callback while env vars remain the temporary override path.
  106. View the effective and stored redirect URI for an app:
  107. ```bash
  108. xurl auth apps redirect-uri get my-app
  109. ```
  110. Set the stored redirect URI for an app:
  111. ```bash
  112. xurl auth apps redirect-uri set my-app http://localhost:8080/callback
  113. ```
  114. Remove an app:
  115. ```bash
  116. xurl auth apps remove old-app
  117. ```
  118. Set the default app and user — **interactive picker** (uses Bubble Tea):
  119. ```bash
  120. xurl auth default
  121. ```
  122. Set the default app and user — **single command**:
  123. ```bash
  124. xurl auth default my-app # set default app
  125. xurl auth default my-app alice # set default app + default user
  126. ```
  127. Use a specific app for a single request:
  128. ```bash
  129. xurl --app dev-app /2/users/me
  130. ```
  131. ### Authentication Status
  132. View authentication status across all apps:
  133. ```bash
  134. xurl auth status
  135. ```
  136. This output shows the effective redirect URI for each app and, when `REDIRECT_URI` is set in the environment, also shows the stored app value separately so precedence is visible.
  137. Example output:
  138. ```
  139. ▸ my-app [client_id: VUttdG9P…]
  140. redirect_uri: http://localhost:8080/callback [app config]
  141. ▸ oauth2: alice
  142. oauth2: bob
  143. oauth1: ✓
  144. bearer: ✓
  145. dev-app [client_id: OTHER789…]
  146. redirect_uri: http://localhost:8080/callback [built-in default]
  147. oauth2: (none)
  148. oauth1: –
  149. bearer: –
  150. ```
  151. ### X Platform Enrollment Troubleshooting
  152. If OAuth succeeds but reads like `xurl whoami` fail with an error body containing `client-forbidden` or `client-not-enrolled`, the current X platform fix is to move the app into the `Pay-per-use` package and use the `Production` environment in the developer console. This is an X platform enrollment issue, not a local callback-listener issue in `xurl`.
  153. `▸` on the left = default app. `▸` next to a user = default user.
  154. ### Clear Authentication
  155. ```bash
  156. xurl auth clear --all # Clear all tokens
  157. xurl auth clear --oauth1 # Clear OAuth 1.0a tokens
  158. xurl auth clear --oauth2-username USERNAME # Clear specific OAuth 2.0 token
  159. xurl auth clear --bearer # Clear bearer token
  160. ```
  161. ### Making Requests
  162. Basic GET request:
  163. ```bash
  164. xurl /2/users/me
  165. ```
  166. Custom HTTP method:
  167. ```bash
  168. xurl -X POST /2/tweets -d '{"text":"Hello world!"}'
  169. ```
  170. Add headers:
  171. ```bash
  172. xurl -H "Content-Type: application/json" /2/tweets
  173. ```
  174. Specify authentication type:
  175. ```bash
  176. xurl --auth oauth2 /2/users/me
  177. xurl --auth oauth1 /2/tweets
  178. xurl --auth app /2/users/me
  179. ```
  180. Use specific OAuth 2.0 account:
  181. ```bash
  182. xurl --username johndoe /2/users/me
  183. ```
  184. ### Streaming Responses
  185. Streaming endpoints (like `/2/tweets/search/stream`) are automatically detected and handled appropriately. The tool will automatically stream the response for these endpoints:
  186. - `/2/tweets/search/stream`
  187. - `/2/tweets/sample/stream`
  188. - `/2/tweets/sample10/stream`
  189. - `/2/tweets/firehose/stream/lang/en`
  190. - `/2/tweets/firehose/stream/lang/ja`
  191. - `/2/tweets/firehose/stream/lang/ko`
  192. - `/2/tweets/firehose/stream/lang/pt`
  193. For example:
  194. ```bash
  195. xurl /2/tweets/search/stream
  196. ```
  197. You can also force streaming mode for any endpoint using the `--stream` or `-s` flag:
  198. ```bash
  199. xurl -s /2/users/me
  200. ```
  201. ### Printing an Access Token
  202. `xurl token` prints a valid OAuth2 access token for the active app to stdout (a single line, no decoration). If the stored token has expired it is refreshed and persisted first. This command never opens a browser, so it is safe to use in scripts:
  203. ```bash
  204. xurl token # token for the default app/user
  205. xurl token --app my-app # token for a specific app
  206. xurl token -u alice # token for a specific OAuth2 user
  207. TOKEN=$(xurl token) && curl -H "Authorization: Bearer $TOKEN" https://api.x.com/2/users/me
  208. ```
  209. If no token is available (and none can be refreshed), it exits non-zero with a hint to run `xurl auth oauth2`.
  210. ### MCP Server (`xurl mcp`)
  211. `xurl mcp` turns xurl into a [Model Context Protocol](https://modelcontextprotocol.io) bridge for the hosted X API MCP server. It reads newline-delimited JSON-RPC from stdin, relays each message to a remote Streamable HTTP MCP endpoint with an `Authorization: Bearer <token>` header, and writes the server's responses (plain JSON or `text/event-stream`) back to stdout as newline-delimited JSON. The MCP session id is maintained automatically and the token is refreshed in-process as it expires.
  212. Because X's OAuth requires your own app (there is no dynamic client registration), xurl holds the app identity and mints/refreshes the token. On first run with no cached token, the bridge opens the browser for a one-time OAuth2 login using the `CLIENT_ID`/`CLIENT_SECRET` from its environment, then caches and auto-refreshes the token for subsequent runs. The MCP handshake is held until that login completes, so give the server a generous `startup_timeout_sec`.
  213. Use it directly from any MCP client (Claude Desktop, Cursor, etc.) with a standard MCP server config — no separate install step is needed thanks to the npm launcher:
  214. ```json
  215. {
  216. "mcpServers": {
  217. "xapi": {
  218. "command": "npx",
  219. "args": ["-y", "@xdevplatform/xurl", "mcp", "https://api.x.com/mcp"],
  220. "env": { "CLIENT_ID": "...", "CLIENT_SECRET": "..." },
  221. "startup_timeout_sec": 300
  222. }
  223. }
  224. }
  225. ```
  226. Requirements for the first-run browser login: a browser on the machine running the client, and your X app must have the OAuth2 redirect URI `http://localhost:8080/callback` registered (or set `REDIRECT_URI` to one that is). On a headless host with no reachable browser, authenticate out-of-band first with `xurl auth oauth2 --headless` (the bridge then just reuses the cached token).
  227. The `<url>` positional is optional and defaults to `https://api.x.com/mcp`. `--app` is honored, so you can point a client at a specific registered app:
  228. ```bash
  229. xurl --app my-app mcp # bridge the default endpoint using my-app
  230. xurl mcp https://api.x.com/mcp # explicit endpoint
  231. ```
  232. All diagnostics are written to stderr so stdout stays a clean JSON-RPC channel.
  233. ### Temporary Webhook Setup
  234. `xurl` can help you quickly set up a temporary webhook URL to receive events from the X API. This is useful for development and testing.
  235. 1. **Start the local webhook server with ngrok:**
  236. Run the `webhook start` command. This will start a local server and use ngrok to create a public URL that forwards to your local server. You will be prompted for your ngrok authtoken if it's not already configured via the `NGROK_AUTHTOKEN` environment variable.
  237. ```bash
  238. xurl webhook start
  239. # Or with a specific port and output file for POST bodies
  240. xurl webhook start -p 8081 -o webhook_events.log
  241. ```
  242. The command will output an ngrok URL (e.g., `https://your-unique-id.ngrok-free.app/webhook`). Note this URL.
  243. 2. **Register the webhook with the X API:**
  244. Use the ngrok URL obtained in the previous step to register your webhook. You'll typically use app authentication for this.
  245. ```bash
  246. # Replace https://your-ngrok-url.ngrok-free.app/webhook with the actual URL from the previous step
  247. xurl --auth app /2/webhooks -d '{"url": "<your ngrok url>"}' -X POST
  248. ```
  249. Your local `xurl webhook start` server will then handle the CRC handshake from Twitter and log incoming POST events (and write them to a file if `-o` was used).
  250. ### Media Upload
  251. The tool supports uploading media files to the X API using the chunked upload process.
  252. Upload a media file (the media type and category are auto-detected from the file extension):
  253. ```bash
  254. xurl media upload path/to/file.mp4
  255. xurl media upload path/to/photo.jpg
  256. ```
  257. Override the auto-detected media type and category when needed:
  258. ```bash
  259. xurl media upload --media-type image/jpeg --category tweet_image path/to/image.jpg
  260. ```
  261. Check media upload status:
  262. ```bash
  263. xurl media status MEDIA_ID
  264. ```
  265. Wait for media processing to complete:
  266. ```bash
  267. xurl media status --wait MEDIA_ID
  268. ```
  269. #### Direct Media Upload
  270. Most users should just use `xurl media upload` above. If you need to drive the
  271. chunked upload manually, use the `-F` flag with the path-style endpoints that
  272. `xurl media upload` itself uses:
  273. 1. First, initialize the upload:
  274. ```bash
  275. xurl -X POST /2/media/upload/initialize -d '{"total_bytes": FILE_SIZE, "media_type": "video/mp4", "media_category": "tweet_video"}'
  276. ```
  277. 2. Then, append the media chunks (repeat with an increasing `segment_index`):
  278. ```bash
  279. xurl -X POST -F path/to/file.mp4 /2/media/upload/MEDIA_ID/append
  280. ```
  281. 3. Finally, finalize the upload:
  282. ```bash
  283. xurl -X POST /2/media/upload/MEDIA_ID/finalize
  284. ```
  285. 4. Check the status:
  286. ```bash
  287. xurl '/2/media/upload?command=STATUS&media_id=MEDIA_ID'
  288. ```
  289. ### Encrypted Chat (`xurl chat`)
  290. `xurl chat` is a full end-to-end encrypted [XChat](https://docs.x.com/) client. Encryption and
  291. decryption happen locally using the official [chat-xdk](https://github.com/xdevplatform/chat-xdk)
  292. crypto library; the server only ever sees ciphertext.
  293. **Keys must already exist.** xurl never generates or registers encryption keys — the
  294. account needs XChat keys from another client (e.g. the X app). Bring them to this
  295. machine once (needs an OAuth2 login with the `dm.read` + `dm.write` scopes):
  296. ```bash
  297. xurl chat keys restore # recover from Juicebox with your PIN, or
  298. xurl chat keys import # paste a private-key blob exported elsewhere
  299. xurl chat keys status # local + registered key state and fingerprint
  300. ```
  301. Conversations are addressed by `@username`, user id, or conversation id (`123-456`, `g123`):
  302. ```bash
  303. xurl chat conversations # list your inbox
  304. xurl chat read @bob [-n 50] [--json] # decrypted history (auto marks read)
  305. xurl chat listen @bob # live tail (Ctrl-C to stop)
  306. xurl chat send @bob "hello" # send (new 1:1 keys itself)
  307. xurl chat send @bob "look" --file photo.png # attach an encrypted file
  308. xurl chat send @bob "ok" --reply-to SEQUENCE_ID # threaded reply (id from read --json)
  309. xurl chat download @bob MEDIA_HASH_KEY -o out.png # download + decrypt an attachment
  310. xurl chat rotate @bob # rotate the conversation key
  311. xurl chat add-members g123 @carol # add a group member (rotates the key)
  312. xurl chat mark-read @bob # (also automatic on read/listen/send)
  313. xurl chat typing @bob # (also automatic before send)
  314. ```
  315. `read`, `listen`, and `send` mark the conversation read automatically, and `send` sends a
  316. typing indicator first; suppress with `--no-mark-read` / `--no-typing`. `rotate` and
  317. `add-members` change the key for every participant and protect future messages only —
  318. old history stays readable only to holders of the earlier key versions.
  319. Notes:
  320. - Keys not already registered on the account are rejected on restore/import; xurl never
  321. writes to Juicebox or the key-registration endpoint.
  322. - Private keys live in `~/.xurl/keys.yml` (mode 600). Losing it is safe as long as the
  323. Juicebox backup (made by the original client) still exists.
  324. - `chat` is supported on macOS (Intel/Apple Silicon) and Linux (amd64), and the release
  325. binaries (Homebrew, npm, GitHub releases) include it on those platforms. On other
  326. platforms (Windows, Linux arm64/i386) `xurl chat` prints a stub explaining it is
  327. unavailable. Source builds on supported platforms need cgo:
  328. `CGO_ENABLED=1 go install github.com/xdevplatform/xurl@latest`.
  329. ## Token Storage
  330. `~/.xurl` is a directory: tokens and app credentials live in `~/.xurl/auth.yml`, and XChat private keys live in `~/.xurl/keys.yml`. Each registered app has its own isolated set of tokens. Example `auth.yml`:
  331. ```yaml
  332. apps:
  333. my-app:
  334. client_id: abc123
  335. client_secret: secret456
  336. redirect_uri: http://localhost:8080/callback
  337. default_user: alice
  338. oauth2_tokens:
  339. alice:
  340. type: oauth2
  341. oauth2:
  342. access_token: "..."
  343. refresh_token: "..."
  344. expiration_time: 1234567890
  345. bearer_token:
  346. type: bearer
  347. bearer: "AAAA..."
  348. default_app: my-app
  349. ```
  350. > **Migration:** A single-file `~/.xurl` from a previous version migrates automatically to `~/.xurl/auth.yml` on first use (pre-v1.0 JSON-format files are also converted to the YAML multi-app format, preserving tokens in a `default` app).
  351. ## Contributing
  352. Contributions are welcome!
  353. ## License
  354. This project is open-sourced under the MIT License - see the LICENSE file for details.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.