# twitter-cli — Twitter API CLI for AI agents

> Current: 1.0.0 (2026-04-17)
> All output is strict JSONL on stdout. Tracing logs on stderr (default: off).
> Exit codes are deterministic: 0=success, 1-12=specific error types.

## Start here
- [Getting Started](./getting-started.md)
- [Output Schema & Error Codes](./output-schema.md)

## Commands (15 actions total)

- [dm](./dm.md) — send, send-batch, inbox
- [posts](./posts.md) — create, delete, like, unlike, retweet, unretweet
- [user](./user.md) — get, get-by-id
- [search](./search.md) — top, latest
- [upload](./upload.md) — image
- [settings](./settings.md) — get

## Global flags (all commands)

```
--cookies-file <PATH>          Auth source 1 (highest priority)
--cookies-stdin                Auth source 2 (explicit stdin, 5s timeout)
--profile <NAME>               Auth source 4 (~/.x-api/config.toml)
--proxy <URL>                  Proxy URL (overrides profile.proxy)
--request-timeout-secs <N>     Per-request timeout, default 30
--log-level <LEVEL>            stderr level: off|error|warn|info|debug|trace
--log-format <FORMAT>          stderr format: json|compact (default json)
--ja3 <BOOL>                   JA3/TLS fingerprint emulation, default true
```

## Auth priority chain

```
1. --cookies-file <path>
2. --cookies-stdin or non-tty stdin (5s timeout)
3. X_API_COOKIES_FILE env var
4. ~/.x-api/config.toml profile.cookies_file
```

## Output formats

Single command: one-line JSON `{"success":bool,"data":T|null,"error":ErrorObj|null,"meta":{...}}`

Batch command (dm send-batch): multi-line JSONL with `type` field:
- `{"type":"header","command":"...","schema_version":"1.0","expected_count":N,"meta":{...}}`
- `{"type":"item","index":N,"success":bool,"data":{...}|null,"error":{...}|null}`
- `{"type":"summary","total":N,"success_count":N,"fail_count":N,"elapsed_ms":N}`

## Error codes & exit codes

| code | exit | retryable |
|------|------|-----------|
| INVALID_ARGS | 2 | false |
| AUTH_FAILED | 3 | false |
| NETWORK | 4 | true |
| RATE_LIMIT | 5 | true |
| NOT_FOUND | 6 | false |
| SERVER | 7 | true |
| DUPLICATE | 8 | false |
| MEDIA_UPLOAD_FAILED | 9 | false |
| CONTENT_VIOLATION | 10 | false |
| DEPRECATED_COMMAND | 11 | false |
| CONFIG_PARSE_ERROR | 12 | false |
| UNKNOWN | 1 | false |

## Full context (one-shot)
- [llms-full.txt](./llms-full.txt)