> ## 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 — X API를 위한 curl 스타일 커맨드라인 클라이언트

> 내장 OAuth를 갖춘 X API용 curl 스타일 CLI인 xurl을 설치하고 사용하여 엔드포인트를 테스트하고, 요청에 서명하고, 터미널에서 프로토타입을 만들어 보세요.

[xurl](https://github.com/xdevplatform/xurl)은 X API를 위한 curl과 유사한 커맨드라인 도구입니다. OAuth 인증을 자동으로 처리해 주므로 토큰을 수동으로 관리하거나 요청에 서명할 필요 없이 API 요청을 보낼 수 있습니다.

<Card title="GitHub repository" icon="github" href="https://github.com/xdevplatform/xurl">
  소스 코드, 릴리스 및 문서.
</Card>

***

## 설치

Go로 설치하거나 [releases](https://github.com/xdevplatform/xurl/releases)에서 미리 빌드된 바이너리를 다운로드하세요.

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

***

## 설정

### 1. X 앱 만들기

xurl은 사용자 본인의 개발자 앱을 사용해 인증합니다. [X 개발자 포털](https://developer.x.com)에서:

1. **OAuth 2.0**이 활성화된 앱을 만들거나 엽니다.
2. 리다이렉트 URI `http://localhost:8080/callback`을 앱에 등록합니다.
3. "Keys and tokens" 페이지에서 앱의 **Client ID**와 **Client Secret**을 복사합니다.

### 2. 자격 증명 설정

xurl을 실행할 동일한 셸에서 자격 증명을 export 하세요:

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

### 3. 인증

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

이 명령은 브라우저 기반 OAuth 흐름을 엽니다. 인증이 완료되면 xurl이 토큰을 `~/.xurl`에 로컬로 저장하므로 다시 인증할 필요가 없습니다.

<Warning>
  브라우저에 \*\*"Something went wrong — You weren't able to give access to the App"\*\*이 표시된다면, xurl이 유효한 자격 증명 없이 로그인을 시작한 것입니다. `xurl auth oauth2`를 실행한 셸에서 `CLIENT_ID`와 `CLIENT_SECRET`이 export되어 있는지, 그리고 `http://localhost:8080/callback`이 앱에 리다이렉트 URI로 등록되어 있는지 확인하세요.
</Warning>

***

## 사용법

### 원시 API 요청

xurl을 curl처럼 사용하면 됩니다 — 인증 헤더는 자동으로 처리됩니다:

```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!"}'
```

### 단축 명령어

xurl에는 일반적인 작업을 위한 내장 단축 명령어가 포함되어 있습니다:

```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!"
```

***

## 왜 xurl을 사용해야 하나요?

| 기능             | curl             | xurl                      |
| :------------- | :--------------- | :------------------------ |
| **인증**         | 수동 OAuth 헤더 설정   | 자동 — `xurl auth`를 한 번만 실행 |
| **토큰 관리**      | 갱신/로테이션을 직접 처리   | 내장 토큰 저장 및 갱신             |
| **API 단축 명령어** | 전체 URL 필요        | 일반 작업을 위한 단축 명령어          |
| **요청 서명**      | 수동 OAuth 1.0a 서명 | 모든 요청에 대해 자동              |

***

## AI 에이전트와 함께 xurl 사용하기

xurl에는 기능을 머신 판독 가능한 형식으로 기술한 [`SKILL.md`](https://github.com/xdevplatform/xurl/blob/main/SKILL.md) 파일이 포함되어 있습니다. AI 에이전트는 이를 이용해 사용자 대신 xurl 명령어를 어떻게 호출해야 하는지 이해할 수 있습니다.

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

***

## 관련 자료

<CardGroup cols={2}>
  <Card title="첫 요청 보내기" icon="rocket" href="/make-your-first-request">
    cURL 또는 SDK를 사용해 X API로 시작하세요.
  </Card>

  <Card title="API Playground" icon="flask" href="https://github.com/xdevplatform/playground">
    모의 데이터로 로컬에서 엔드포인트를 테스트하세요 — API 크레딧이 필요 없습니다.
  </Card>
</CardGroup>