WEIR
Get a key
Theme

X API CLI: xurl Install, Auth and Commands (2026)

xurl is the official X API CLI. Install v1.3.4, log in by OAuth 2.0, OAuth 1.0a or bearer token, find where tokens live, and see when plain curl is enough.


Published · Updated · 6 min read

Cover image: X's own curl, OAuth built in

The official X API CLI is xurl, a curl-style tool from X that signs each request for you, so xurl /2/users/me works after one login.

This guide is for developers who test the X (Twitter) API from a terminal. You get the install, the three login modes, common commands and where tokens live, read from xurl's README and source at v1.3.4. We have no X app, so we didn't run xurl itself.

Install it and log in with your app's keys:

npm install -g @xdevplatform/xurl
xurl auth apps add my-app --client-id YOUR_CLIENT_ID --client-secret YOUR_CLIENT_SECRET
xurl auth oauth2 --app my-app
xurl /2/users/me
  1. Install xurlnpm, Homebrew, the script or go install.
  2. Register your appClient ID, secret and callback URL.
  3. Log inxurl auth oauth2 opens a browser.
  4. Send requestsA path, or a shortcut such as xurl search.

What is xurl, the official X API CLI?

xurl lives in X's xdevplatform organization on GitHub. Its repo calls it "The official CLI for the X API," and X's Tools and Libraries page lists it.

We read its GitHub releases and source on 24 October 2026:

v1.3.4latest release, 29 September 2026
29shortcut commands, from post to dm
24OAuth 2.0 scopes it asks for at login

Version 1.0.0 shipped on 20 February 2026. xurl mcp arrived in v1.2.0 that June, and the encrypted xurl chat client in v1.3.0 in July.

Step 1: Install xurl

The README lists four ways. Pick one:

brew install --cask xdevplatform/tap/xurl
npm install -g @xdevplatform/xurl
curl -fsSL https://raw.githubusercontent.com/xdevplatform/xurl/main/install.sh | bash
go install github.com/xdevplatform/xurl@latest

X's own xurl page lists only Go and the release binaries. The script installs to ~/.local/bin. Read any script before you pipe it to bash.

Step 2: Log in with OAuth 2.0, OAuth 1.0a or a bearer token

xurl needs your own X developer app. Our guide to getting an X API key shows where each credential lives.

xurl auth apps add my-app --client-id ID --client-secret SECRET
xurl auth oauth2 --app my-app             # opens a browser
xurl auth oauth2 --app my-app --headless  # paste the redirect URL back
xurl auth oauth1 --consumer-key KEY --consumer-secret SECRET \
  --access-token TOKEN --token-secret SECRET
cat token.txt | xurl auth app-only -      # bearer, kept out of shell history
xurl auth status
  • Register the callback. xurl's default is http://localhost:8080/callback, and it must be on your app.
  • OAuth 2.0 uses PKCE with S256, with a new verifier each login, per the source.
  • It asks for 24 scopes, every one in X's docs table, including dm.write and users.email. v1.3.4 has no flag to ask for fewer.
  • client-not-enrolled after login? The README's fix: move the app to Pay-per-use and Production.

Our X API OAuth 2.0 guide explains the scopes and the 2-hour token.

Where does xurl store tokens?

Everything lives in ~/.xurl/auth.yml: client secrets, access and refresh tokens, and bearer tokens. The source writes it with file mode 600, in a folder only you can open.

  • The file is plain YAML. Anyone who copies it can act as you.
  • Without --auth, xurl picks your OAuth 2.0 token, then OAuth 1.0a, then the bearer token.
  • xurl token prints a fresh access token, refreshing it first if needed, for scripts.

Step 3: Run common xurl commands

Requests look like curl with the host left off:

xurl /2/users/by/username/XDevelopers
xurl "/2/tweets/search/recent?query=from:XDevelopers&max_results=10"
xurl -X POST /2/tweets -d '{"text":"Hello from xurl"}'
xurl search "X API"
xurl media upload photo.jpg
xurl --auth app /2/tweets/search/stream
  • Shortcuts cover 29 jobs in v1.3.4, including post, reply, like, follow, bookmarks and dm.
  • Media upload runs X's three-step chunked upload. xurl media status --wait ID waits for processing.
  • Streams print as they arrive. X's spec accepts only an app-only token on the filtered stream, and xurl tries OAuth 2.0 first, so add --auth app.

Every call bills like any other X API call. A post costs $0.015 on X's pricing page, or $0.200 with a link.

xurl mcp and AI agents

xurl mcp connects an AI client to X's hosted MCP server at api.x.com/mcp. X has no dynamic client registration, so xurl holds your app's keys and refreshes the token. Our X official MCP server guide covers the setup and costs.

Agents also use xurl through a skill: X's xurl page says the repo ships a SKILL.md for them. We searched @XDevelopers' posts for "xurl" through Weir on 24 October 2026, for 2 credits. The newest match was an X Article, trimmed:

{
  "createdAt": "2026-05-19T22:55:02.000Z",
  "likeCount": 1495,
  "viewCount": 802850,
  "article": { "title": "X API + Hermes via xurl skill" }
}

Its preview says Hermes, an open-source agent, ships with an xurl skill "that lets the agent read and write to X on your behalf."

xurl vs curl: which X API CLI should you use?

As an X API curl alternative, xurl hits the same API at the same price. The difference is who handles auth:

Job curl xurl
Install On most systems already npm, Homebrew, script, Go
Bearer token One header xurl auth app-only once
OAuth 1.0a Sign every request yourself Signed for you
OAuth 2.0 PKCE Run the flow and refresh Browser login, refresh
Media upload Three calls by hand xurl media upload
Streams Add -N to stop buffering Detected by path

Pick curl for app-only reads in scripts and CI, where one header is enough. Pick xurl to act as a user or to try endpoints by hand. Our X API curl examples cover the curl side.

Reading public data without an X app

We run Weir, a read-only API for public X data, so weigh this part knowing that. It needs no X app or OAuth, just one key with plain curl:

curl --request POST --url https://api.weirapp.io/v1/x/search \
  --header "Authorization: Bearer $WEIR_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{"fromUsers":["XDevelopers"],"query":"xurl","limit":1}'

It's the search we ran above through Weir's MCP server. It costs 1 credit per call plus 1 per post, and 5,000 credits a month are free.

When not to use Weir

  • You post, like, DM or upload media. Weir is read-only, and xurl does all four.
  • Live streams matter. xurl reads X's streams, and Weir has none.
  • The data is your own bookmarks or DMs. Those need your own X token.
  • A contract with X is required, or X's own terms.

FAQ

Is there an official Twitter API command line tool?

Yes: xurl, X's official command line tool for the X API, written in Go. It works like curl, but it runs OAuth 2.0, OAuth 1.0a or bearer auth for you and stores the tokens in ~/.xurl.

Is xurl free?

The tool is free and open source under the MIT license. The API isn't: X bills each call at pay-per-use rates, such as $0.005 per post read, as of October 2026.

Does xurl work on Windows?

Yes. Releases include Windows builds, and v1.1.0 fixed OAuth 2.0 login on Windows in April 2026. The README says xurl chat isn't available there.

What happened to twurl?

twurl was X's earlier CLI, written in Ruby. Its last release, v0.9.6, came out in August 2020. X's Tools and Libraries page lists xurl, not twurl.

Sources

All checked on 24 October 2026:

Keep reading