xurl
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.
Badge for your README
Markdown
[](/listings/xdevplatform--xurl)HTML
<a href="/listings/xdevplatform--xurl"><img src="/api/listings/xdevplatform--xurl/badge.svg" alt="findsafeskills safety rating" /></a>Install
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.
- ---
- name: xurl
- 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.
- ---
- # 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.
- ---
- ## 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 anything under `~/.xurl/` (or copies of it) to the LLM context.
- - `~/.xurl/keys.yml` contains XChat **private encryption keys** — the strictest no-read rule applies.
- - 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.
- - Never ask the user to paste credentials/tokens into chat.
- - The user must fill `~/.xurl/auth.yml` 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.
- - 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.
- - `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.
- - 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 against the app that holds those credentials:
- ```bash
- xurl auth oauth2 --app APP_NAME
- ```
- You can also run `xurl auth default APP_NAME` first and then use `xurl auth oauth2`.
- 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.
- 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
- xurl auth apps redirect-uri get prod-app
- xurl auth apps redirect-uri set prod-app http://localhost:8080/callback
- ```
- ### 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/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.
- ---
- ## 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` |
- | List a user's posts | `xurl posts @handle -n 10` |
- | 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` |
- | **Encrypted Chat (XChat)** | |
- | Chat key status | `xurl chat keys status` |
- | Restore chat keys | `xurl chat keys restore` (PIN prompted; never pass `--pin` in agent sessions) |
- | Import chat keys | `xurl chat keys import` (blob prompted; avoid passing it as an argument) |
- | List chat inbox | `xurl chat conversations` |
- | Read a conversation | `xurl chat read @handle -n 50` |
- | Send encrypted message | `xurl chat send @handle "message"` |
- | Listen for new messages | `xurl chat listen @handle` |
- | Rotate a conversation key | `xurl chat rotate CONV --yes` (write op — see notes) |
- | Send with an attachment | `xurl chat send CONV "text" --file path/to/img.png` |
- | Reply to a message | `xurl chat send CONV "text" --reply-to SEQUENCE_ID` |
- | Download an attachment | `xurl chat download CONV MEDIA_HASH_KEY -o out.png` |
- | Add group members | `xurl chat add-members GROUP @user --yes` (write op) |
- | Mark read (explicit) | `xurl chat mark-read CONV` |
- | Typing indicator (explicit) | `xurl chat typing CONV` |
- | **App Management** | |
- | Register app | Manual, outside agent (do not pass secrets via agent) |
- | List apps | `xurl auth apps list` |
- | Update app config | Manual, outside agent (do not pass secrets via agent) |
- | View app redirect URI | `xurl auth apps redirect-uri get [NAME]` |
- | Set app redirect URI | `xurl auth apps redirect-uri set NAME URI` |
- | 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
- # List a user's recent posts (by @username)
- xurl posts elonmusk
- xurl posts @XDevelopers -n 25
- ```
- ### 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
- ```
- ### Encrypted Chat (XChat)
- `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.
- **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.
- 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.
- ```bash
- # 1. Keys — one-time setup (xurl never generates/registers keys)
- xurl chat keys status # local key presence/fingerprint + registered versions
- xurl chat keys restore # recover from Juicebox; prompts for the PIN (no echo)
- xurl chat keys import # paste an exported private-key blob (no echo)
- # 2. Browse the inbox
- xurl chat conversations # pretty list; decrypts group names when keys are present
- xurl chat conversations --json # raw JSON
- # 3. Read history (oldest first; auto-marks the conversation read)
- xurl chat read @someuser
- xurl chat read g1234567890 -n 50 # -n = how many events to fetch (max 100)
- xurl chat read @someuser --json # decrypted events as JSON (each has id, sequence_id, content)
- xurl chat read @someuser --no-mark-read # read without sending a read receipt
- # 4. Send (a new 1:1 sets up its key automatically; both sides need keys)
- xurl chat send @someuser "hey, encrypted!"
- xurl chat send @someuser "look" --file ./photo.png # attach an encrypted file
- xurl chat send @someuser "agreed" --reply-to SEQUENCE_ID # threaded reply (id from `read --json`)
- # send auto-sends a typing indicator first and marks read after;
- # suppress with --no-typing / --no-mark-read
- # 5. Attachments — inbound messages show "📎 attachment <media_hash_key>"
- xurl chat download @someuser MEDIA_HASH_KEY -o out.png # download + decrypt
- # 6. Live tail (poll loop; Ctrl-C to stop; auto-marks new messages read)
- xurl chat listen @someuser
- xurl chat listen g1234567890 --interval 5
- # 7. Read receipts / typing (also happen automatically on read/send)
- xurl chat mark-read @someuser # mark read up to the newest message
- xurl chat typing @someuser # send a typing indicator
- # 8. Group key management (writes visible to all participants)
- xurl chat add-members g123 @newuser # add a member (rotates the key; prompts, or --yes)
- xurl chat rotate g123 # rotate the conversation key; prompts, or --yes
- # Rotate when a key may be exposed, or to grant a member whose keys were
- # registered after the last rotation access going forward. Future messages
- # only — old history stays readable only to holders of the old key versions.
- ```
- Notes for agents:
- - 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.
- - 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.
- - **`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.
- - Decrypt warnings for individual events go to stderr and are non-fatal; the rest of the conversation still renders.
- - 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.
- - `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`.
- ### 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) |
- ---
- ## 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`. 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.
- - 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.
- ---
- ## 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, tokens, and optional stored `redirect_uri`. Configure credentials manually outside agent/LLM context, then switch with `xurl auth default` or `--app`.
- - **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.
- - **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.
- - **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`.
- - **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 a directory; `~/.xurl/auth.yml` holds each app's credentials and tokens. Never read or send anything under `~/.xurl/` to LLM context.
- - **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.
- - **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.
- - **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.
- - **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.
- # xurl - A curl-like CLI Tool for the X API
- A command-line tool for interacting with the X (formerly Twitter) API, supporting both OAuth 1.0a and OAuth 2.0 authentication.
- ## Features
- - **Multi-app support** — register multiple X API apps with separate credentials and tokens
- - OAuth 2.0 PKCE flow authentication
- - OAuth 1.0a authentication
- - Multiple OAuth 2.0 account support per app
- - Default app and default user selection (interactive Bubble Tea picker or single command)
- - Persistent token storage in YAML (`~/.xurl/auth.yml`), auto-migrates from the legacy single-file layout
- - HTTP request customization (headers, methods, body)
- - Per-request app override with `--app`
- - End-to-end encrypted XChat client (`xurl chat`) built on the official chat-xdk crypto library
- ## Installation
- ### Homebrew (macOS)
- ```bash
- brew install --cask xdevplatform/tap/xurl
- ```
- ### npm
- ```bash
- npm install -g @xdevplatform/xurl
- ```
- ### Shell script (no sudo required)
- ```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
- ```
- ## Usage
- ### Authentication
- You must have a developer account and app to use this tool.
- #### Register an app
- Register your X API app credentials so they're stored in `~/.xurl/auth.yml` (no env vars needed after this):
- ```bash
- xurl auth apps add my-app --client-id YOUR_CLIENT_ID --client-secret YOUR_CLIENT_SECRET
- ```
- If you want the app to keep its own callback configuration in `~/.xurl/auth.yml`, you can store the redirect URI there too:
- ```bash
- xurl auth apps add my-app --client-id YOUR_CLIENT_ID --client-secret YOUR_CLIENT_SECRET --redirect-uri http://localhost:8080/callback
- ```
- You can register multiple apps:
- ```bash
- xurl auth apps add prod-app --client-id PROD_ID --client-secret PROD_SECRET
- xurl auth apps add dev-app --client-id DEV_ID --client-secret DEV_SECRET
- ```
- > **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.
- >
- > `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`.
- #### OAuth 2.0 User-Context
- **Note:** For OAuth 2.0 authentication, you must specify the redirect URI in the [X Developer Console](https://console.x.com).
- 1. Create an app in the [X Developer Console](https://console.x.com).
- 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`.
- 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.
- 
- 
- 3. Register the app (if you haven't already):
- ```bash
- xurl auth apps add my-app --client-id YOUR_CLIENT_ID --client-secret YOUR_CLIENT_SECRET
- ```
- 4. Get your access keys for the registered app:
- ```bash
- xurl auth oauth2 --app my-app
- ```
- 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`.
- **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`:
- ```bash
- xurl auth oauth2 --app my-app --headless
- ```
- 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.
- 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:
- 1. Go to `Apps` -> `Manage apps`
- 2. Open the app
- 3. Use `Move to package`
- 4. Choose `Pay-per-use`
- 5. Move the app to the `Production` environment
- Without that enrollment step, `xurl whoami` and other `/2/*` reads can fail even when the OAuth callback and tokens are valid.
- If X does not return your username reliably through `/2/users/me`, authenticate with an explicit handle instead:
- ```bash
- xurl auth oauth2 --app my-app YOUR_USERNAME
- ```
- That keeps the OAuth2 token associated with the expected username and also gives shortcut commands a fallback when `/2/users/me` is unavailable.
- #### App-only authentication (Bearer Token):
- ```bash
- xurl auth app-only BEARER_TOKEN
- cat token.txt | xurl auth app-only - # read from stdin (keeps it out of shell history)
- ```
- 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`.
- > Back-compat: `xurl auth app` and `xurl auth bearer` still work as aliases, and `--bearer-token TOKEN` is still accepted.
- #### OAuth 1.0a authentication:
- ```bash
- xurl auth oauth1 --consumer-key KEY --consumer-secret SECRET --access-token TOKEN --token-secret SECRET
- ```
- ### Multi-App Management
- List registered apps:
- ```bash
- xurl auth apps list
- ```
- Update credentials on an existing app:
- ```bash
- xurl auth apps update my-app --client-id NEW_ID --client-secret NEW_SECRET
- xurl auth apps update my-app --redirect-uri http://localhost:8080/callback
- ```
- `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.
- View the effective and stored redirect URI for an app:
- ```bash
- xurl auth apps redirect-uri get my-app
- ```
- Set the stored redirect URI for an app:
- ```bash
- xurl auth apps redirect-uri set my-app http://localhost:8080/callback
- ```
- Remove an app:
- ```bash
- xurl auth apps remove old-app
- ```
- Set the default app and user — **interactive picker** (uses Bubble Tea):
- ```bash
- xurl auth default
- ```
- Set the default app and user — **single command**:
- ```bash
- xurl auth default my-app # set default app
- xurl auth default my-app alice # set default app + default user
- ```
- Use a specific app for a single request:
- ```bash
- xurl --app dev-app /2/users/me
- ```
- ### Authentication Status
- View authentication status across all apps:
- ```bash
- xurl auth status
- ```
- 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.
- Example output:
- ```
- ▸ my-app [client_id: VUttdG9P…]
- redirect_uri: http://localhost:8080/callback [app config]
- ▸ oauth2: alice
- oauth2: bob
- oauth1: ✓
- bearer: ✓
- dev-app [client_id: OTHER789…]
- redirect_uri: http://localhost:8080/callback [built-in default]
- oauth2: (none)
- oauth1: –
- bearer: –
- ```
- ### X Platform Enrollment Troubleshooting
- 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`.
- `▸` on the left = default app. `▸` next to a user = default user.
- ### Clear Authentication
- ```bash
- xurl auth clear --all # Clear all tokens
- xurl auth clear --oauth1 # Clear OAuth 1.0a tokens
- xurl auth clear --oauth2-username USERNAME # Clear specific OAuth 2.0 token
- xurl auth clear --bearer # Clear bearer token
- ```
- ### Making Requests
- Basic GET request:
- ```bash
- xurl /2/users/me
- ```
- Custom HTTP method:
- ```bash
- xurl -X POST /2/tweets -d '{"text":"Hello world!"}'
- ```
- Add headers:
- ```bash
- xurl -H "Content-Type: application/json" /2/tweets
- ```
- Specify authentication type:
- ```bash
- xurl --auth oauth2 /2/users/me
- xurl --auth oauth1 /2/tweets
- xurl --auth app /2/users/me
- ```
- Use specific OAuth 2.0 account:
- ```bash
- xurl --username johndoe /2/users/me
- ```
- ### Streaming Responses
- Streaming endpoints (like `/2/tweets/search/stream`) are automatically detected and handled appropriately. The tool will automatically stream the response for these endpoints:
- - `/2/tweets/search/stream`
- - `/2/tweets/sample/stream`
- - `/2/tweets/sample10/stream`
- - `/2/tweets/firehose/stream/lang/en`
- - `/2/tweets/firehose/stream/lang/ja`
- - `/2/tweets/firehose/stream/lang/ko`
- - `/2/tweets/firehose/stream/lang/pt`
- For example:
- ```bash
- xurl /2/tweets/search/stream
- ```
- You can also force streaming mode for any endpoint using the `--stream` or `-s` flag:
- ```bash
- xurl -s /2/users/me
- ```
- ### Printing an Access Token
- `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:
- ```bash
- xurl token # token for the default app/user
- xurl token --app my-app # token for a specific app
- xurl token -u alice # token for a specific OAuth2 user
- TOKEN=$(xurl token) && curl -H "Authorization: Bearer $TOKEN" https://api.x.com/2/users/me
- ```
- If no token is available (and none can be refreshed), it exits non-zero with a hint to run `xurl auth oauth2`.
- ### MCP Server (`xurl mcp`)
- `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.
- 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`.
- 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:
- ```json
- {
- "mcpServers": {
- "xapi": {
- "command": "npx",
- "args": ["-y", "@xdevplatform/xurl", "mcp", "https://api.x.com/mcp"],
- "env": { "CLIENT_ID": "...", "CLIENT_SECRET": "..." },
- "startup_timeout_sec": 300
- }
- }
- }
- ```
- 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).
- 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:
- ```bash
- xurl --app my-app mcp # bridge the default endpoint using my-app
- xurl mcp https://api.x.com/mcp # explicit endpoint
- ```
- All diagnostics are written to stderr so stdout stays a clean JSON-RPC channel.
- ### Temporary Webhook Setup
- `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.
- 1. **Start the local webhook server with ngrok:**
- 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.
- ```bash
- xurl webhook start
- # Or with a specific port and output file for POST bodies
- xurl webhook start -p 8081 -o webhook_events.log
- ```
- The command will output an ngrok URL (e.g., `https://your-unique-id.ngrok-free.app/webhook`). Note this URL.
- 2. **Register the webhook with the X API:**
- Use the ngrok URL obtained in the previous step to register your webhook. You'll typically use app authentication for this.
- ```bash
- # Replace https://your-ngrok-url.ngrok-free.app/webhook with the actual URL from the previous step
- xurl --auth app /2/webhooks -d '{"url": "<your ngrok url>"}' -X POST
- ```
- 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).
- ### Media Upload
- The tool supports uploading media files to the X API using the chunked upload process.
- Upload a media file (the media type and category are auto-detected from the file extension):
- ```bash
- xurl media upload path/to/file.mp4
- xurl media upload path/to/photo.jpg
- ```
- Override the auto-detected media type and category when needed:
- ```bash
- xurl media upload --media-type image/jpeg --category tweet_image path/to/image.jpg
- ```
- Check media upload status:
- ```bash
- xurl media status MEDIA_ID
- ```
- Wait for media processing to complete:
- ```bash
- xurl media status --wait MEDIA_ID
- ```
- #### Direct Media Upload
- Most users should just use `xurl media upload` above. If you need to drive the
- chunked upload manually, use the `-F` flag with the path-style endpoints that
- `xurl media upload` itself uses:
- 1. First, initialize the upload:
- ```bash
- xurl -X POST /2/media/upload/initialize -d '{"total_bytes": FILE_SIZE, "media_type": "video/mp4", "media_category": "tweet_video"}'
- ```
- 2. Then, append the media chunks (repeat with an increasing `segment_index`):
- ```bash
- xurl -X POST -F path/to/file.mp4 /2/media/upload/MEDIA_ID/append
- ```
- 3. Finally, finalize the upload:
- ```bash
- xurl -X POST /2/media/upload/MEDIA_ID/finalize
- ```
- 4. Check the status:
- ```bash
- xurl '/2/media/upload?command=STATUS&media_id=MEDIA_ID'
- ```
- ### Encrypted Chat (`xurl chat`)
- `xurl chat` is a full end-to-end encrypted [XChat](https://docs.x.com/) client. Encryption and
- decryption happen locally using the official [chat-xdk](https://github.com/xdevplatform/chat-xdk)
- crypto library; the server only ever sees ciphertext.
- **Keys must already exist.** xurl never generates or registers encryption keys — the
- account needs XChat keys from another client (e.g. the X app). Bring them to this
- machine once (needs an OAuth2 login with the `dm.read` + `dm.write` scopes):
- ```bash
- xurl chat keys restore # recover from Juicebox with your PIN, or
- xurl chat keys import # paste a private-key blob exported elsewhere
- xurl chat keys status # local + registered key state and fingerprint
- ```
- Conversations are addressed by `@username`, user id, or conversation id (`123-456`, `g123`):
- ```bash
- xurl chat conversations # list your inbox
- xurl chat read @bob [-n 50] [--json] # decrypted history (auto marks read)
- xurl chat listen @bob # live tail (Ctrl-C to stop)
- xurl chat send @bob "hello" # send (new 1:1 keys itself)
- xurl chat send @bob "look" --file photo.png # attach an encrypted file
- xurl chat send @bob "ok" --reply-to SEQUENCE_ID # threaded reply (id from read --json)
- xurl chat download @bob MEDIA_HASH_KEY -o out.png # download + decrypt an attachment
- xurl chat rotate @bob # rotate the conversation key
- xurl chat add-members g123 @carol # add a group member (rotates the key)
- xurl chat mark-read @bob # (also automatic on read/listen/send)
- xurl chat typing @bob # (also automatic before send)
- ```
- `read`, `listen`, and `send` mark the conversation read automatically, and `send` sends a
- typing indicator first; suppress with `--no-mark-read` / `--no-typing`. `rotate` and
- `add-members` change the key for every participant and protect future messages only —
- old history stays readable only to holders of the earlier key versions.
- Notes:
- - Keys not already registered on the account are rejected on restore/import; xurl never
- writes to Juicebox or the key-registration endpoint.
- - Private keys live in `~/.xurl/keys.yml` (mode 600). Losing it is safe as long as the
- Juicebox backup (made by the original client) still exists.
- - `chat` is supported on macOS (Intel/Apple Silicon) and Linux (amd64), and the release
- binaries (Homebrew, npm, GitHub releases) include it on those platforms. On other
- platforms (Windows, Linux arm64/i386) `xurl chat` prints a stub explaining it is
- unavailable. Source builds on supported platforms need cgo:
- `CGO_ENABLED=1 go install github.com/xdevplatform/xurl@latest`.
- ## Token Storage
- `~/.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`:
- ```yaml
- apps:
- my-app:
- client_id: abc123
- client_secret: secret456
- redirect_uri: http://localhost:8080/callback
- default_user: alice
- oauth2_tokens:
- alice:
- type: oauth2
- oauth2:
- access_token: "..."
- refresh_token: "..."
- expiration_time: 1234567890
- bearer_token:
- type: bearer
- bearer: "AAAA..."
- default_app: my-app
- ```
- > **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).
- ## Contributing
- Contributions are welcome!
- ## License
- 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 inFree to use. If it’s helped, pass it on.