Skip to content

xurl.mdx

Latest commit

 

History

History
123 lines (83 loc) · 3.66 KB

xurl.mdx

File metadata and controls

123 lines (83 loc) · 3.66 KB
Raw
title xurl — curl-style command line client for the X API
sidebarTitle CLI (xurl)
description Install and use xurl, a curl-style CLI for the X API with built-in OAuth that lets you test endpoints, sign requests, and prototype from the terminal.
keywords
xurl
CLI
command line
curl
X API CLI
API testing
OAuth
developer tools

xurl is a curl-like command-line tool for the X API. It handles OAuth authentication automatically so you can make API requests without manually managing tokens or signing requests.

Source code, releases, and documentation.

Installation

Install with Go, or download a pre-built binary from releases.

go install github.com/xdevplatform/xurl@latest

Setup

1. Create an X app

xurl authenticates using your own developer app. In the X Developer Portal:

  1. Create (or open) an app with OAuth 2.0 enabled.
  2. Register the redirect URI http://localhost:8080/callback on the app.
  3. Copy the app's Client ID and Client Secret from the "Keys and tokens" page.

2. Set your credentials

Export the credentials in the same shell you'll run xurl from:

export CLIENT_ID="your-x-app-client-id"
export CLIENT_SECRET="your-x-app-client-secret"

3. Authorize

xurl auth oauth2

This opens a browser-based OAuth flow. Once authorized, xurl stores your tokens locally in ~/.xurl so you don't need to authenticate again.

If the browser shows **"Something went wrong — You weren't able to give access to the App"**, xurl started the login without valid credentials. Make sure `CLIENT_ID` and `CLIENT_SECRET` are exported in the shell where you ran `xurl auth oauth2`, and that `http://localhost:8080/callback` is registered as a redirect URI on your app.

Usage

Raw API requests

Use xurl like curl — it handles auth headers automatically:

# Look up a user
xurl /2/users/by/username/xdevelopers

# Search recent posts
xurl "/2/tweets/search/recent?query=from:xdevelopers&max_results=10"

# Create a post
xurl -X POST /2/tweets -d '{"text": "Hello from xurl!"}'

Shortcut commands

xurl includes built-in shortcuts for common operations:

# Look up a user by username
xurl user xdevelopers

# Search recent posts
xurl search "X API"

# Post a tweet
xurl post "Hello from xurl!"

Why use xurl?

Feature curl xurl
Authentication Manual OAuth header setup Automatic — just run xurl auth once
Token management You handle refresh/rotation Built-in token storage and refresh
API shortcuts Full URL required Shorthand commands for common tasks
Request signing Manual OAuth 1.0a signing Automatic for all requests

Using xurl with AI agents

xurl includes a SKILL.md file that describes its capabilities in a machine-readable format. AI agents can use this to understand how to invoke xurl commands on your behalf.

npx skills add https://github.com/xdevplatform/xurl

Related

Get started with the X API using cURL or SDKs. Test endpoints locally with mock data — no API credits needed.