> ## Documentation Index
> Fetch the complete documentation index at: https://x-preview-mintlify-0117fede.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# xurl — curl-style command line client for the X API

> 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.

[xurl](https://github.com/xdevplatform/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.

<Card title="GitHub repository" icon="github" href="https://github.com/xdevplatform/xurl">
  Source code, releases, and documentation.
</Card>

***

## Installation

Install with Go, or download a pre-built binary from [releases](https://github.com/xdevplatform/xurl/releases).

```bash theme={null}
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](https://developer.x.com):

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:

```bash theme={null}
export CLIENT_ID="your-x-app-client-id"
export CLIENT_SECRET="your-x-app-client-secret"
```

### 3. Authorize

```bash theme={null}
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.

<Warning>
  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.
</Warning>

***

## Usage

### Raw API requests

Use xurl like curl — it handles auth headers automatically:

```bash theme={null}
# 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:

```bash theme={null}
# 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`](https://github.com/xdevplatform/xurl/blob/main/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.

```bash theme={null}
npx skills add https://github.com/xdevplatform/xurl
```

***

## Related

<CardGroup cols={2}>
  <Card title="Make your first request" icon="rocket" href="/make-your-first-request">
    Get started with the X API using cURL or SDKs.
  </Card>

  <Card title="API Playground" icon="flask" href="https://github.com/xdevplatform/playground">
    Test endpoints locally with mock data — no API credits needed.
  </Card>
</CardGroup>