> ## Documentation Index
> Fetch the complete documentation index at: https://docs.x.com/llms.txt
> Use this file to discover all available pages before exploring further.

# xurl — cliente de linha de comando estilo curl para a X API

> Instale e use o xurl, uma CLI estilo curl para a X API com OAuth integrado que permite testar endpoints, assinar requisições e prototipar direto do terminal.

[xurl](https://github.com/xdevplatform/xurl) é uma ferramenta de linha de comando parecida com o curl para a X API. Ela cuida da autenticação OAuth automaticamente, para que você possa fazer requisições à API sem gerenciar tokens ou assinar requisições manualmente.

<Card title="Repositório no GitHub" icon="github" href="https://github.com/xdevplatform/xurl">
  Código-fonte, releases e documentação.
</Card>

***

## Instalação

Instale com Go ou baixe um binário pré-compilado nas [releases](https://github.com/xdevplatform/xurl/releases).

```bash theme={null}
go install github.com/xdevplatform/xurl@latest
```

***

## Configuração

### 1. Crie um app X

O xurl se autentica usando o seu próprio app de desenvolvedor. No [Portal do Desenvolvedor X](https://developer.x.com):

1. Crie (ou abra) um app com **OAuth 2.0** habilitado.
2. Registre o redirect URI `http://localhost:8080/callback` no app.
3. Copie o **Client ID** e o **Client Secret** do app na página "Keys and tokens".

### 2. Defina suas credenciais

Exporte as credenciais no mesmo shell em que você vai executar o xurl:

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

### 3. Autorize

```bash theme={null}
xurl auth oauth2
```

Isso abre um fluxo OAuth pelo navegador. Uma vez autorizado, o xurl armazena seus tokens localmente em `~/.xurl`, então você não precisa se autenticar novamente.

<Warning>
  Se o navegador mostrar **"Something went wrong — You weren't able to give access to the App"**, o xurl iniciou o login sem credenciais válidas. Certifique-se de que `CLIENT_ID` e `CLIENT_SECRET` estejam exportados no shell onde você executou `xurl auth oauth2`, e de que `http://localhost:8080/callback` esteja registrado como redirect URI no seu app.
</Warning>

***

## Uso

### Requisições brutas à API

Use o xurl como o curl — ele cuida dos cabeçalhos de auth automaticamente:

```bash theme={null}
# Consultar um usuário
xurl /2/users/by/username/xdevelopers

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

# Criar um post
xurl -X POST /2/tweets -d '{"text": "Hello from xurl!"}'
```

### Comandos de atalho

O xurl inclui atalhos integrados para operações comuns:

```bash theme={null}
# Consultar um usuário por username
xurl user xdevelopers

# Buscar posts recentes
xurl search "X API"

# Publicar um tweet
xurl post "Hello from xurl!"
```

***

## Por que usar o xurl?

| Recurso                       | curl                                   | xurl                                            |
| :---------------------------- | :------------------------------------- | :---------------------------------------------- |
| **Autenticação**              | Configuração manual do cabeçalho OAuth | Automática — basta executar `xurl auth` uma vez |
| **Gerenciamento de tokens**   | Você lida com refresh/rotação          | Armazenamento e refresh de tokens integrados    |
| **Atalhos de API**            | URL completa obrigatória               | Comandos abreviados para tarefas comuns         |
| **Assinatura de requisições** | Assinatura OAuth 1.0a manual           | Automática para todas as requisições            |

***

## Usando o xurl com agentes de IA

O xurl inclui um arquivo [`SKILL.md`](https://github.com/xdevplatform/xurl/blob/main/SKILL.md) que descreve suas capacidades em formato legível por máquina. Agentes de IA podem usá-lo para entender como invocar comandos do xurl em seu nome.

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

***

## Relacionados

<CardGroup cols={2}>
  <Card title="Faça sua primeira requisição" icon="rocket" href="/make-your-first-request">
    Comece a usar a X API com cURL ou SDKs.
  </Card>

  <Card title="API Playground" icon="flask" href="https://github.com/xdevplatform/playground">
    Teste endpoints localmente com dados mock — sem gastar créditos da API.
  </Card>
</CardGroup>