npm package: @humebio/hume-x
Description: X/Twitter CLI client and SDK
Latest version: 0.3.2

# hume-x

X/Twitter CLI client and SDK for Node.js.

## Install

```bash
# As SDK (programmatic usage)
npm install @humebio/hume-x

# As global CLI
npm install -g @humebio/hume-x
```

## Features

- **Full API coverage**: tweet, reply, quote, delete, read, search, timeline, engagement, social, lists, trending, notifications, bookmarks, likes, scheduled tweets
- **Media upload**: images (jpg/png/webp), GIFs, videos with chunked upload
- **Cursor-based pagination**: `--cursor` and `--pages` flags for all list commands
- **Trending tabs**: For You, Trending, News, Sports, Entertainment via `--tab`
- **Global CLI flags**: `--auth-token`, `--ct0`, `--plain`, `--no-color`, `--timeout`
- **JSON output**: `--json` for parsed output, `--json-full` for raw API responses
- **Browser cookie auth**: auto-reads credentials from Firefox or Chrome
- **Query ID management**: auto-scrapes from x.com with 24h cache + fallback rotation
- **Rate limit handling**: automatic retry with exponential backoff on 429/5xx
- **Proxy support**: HTTPS/SOCKS5 proxy via `--proxy` flag or env vars
- **Pin/unpin tweets**, **mute/block users**, **scheduled tweets**

## Auth

hume-x resolves credentials in this order:

1. **CLI flags**: `--auth-token` and `--ct0`
2. **Environment variables**: `X_AUTH_TOKEN` + `X_CT0` (or `AUTH_TOKEN` + `CT0`)
3. **Config file**: `~/.config/hume-x/config.json`
4. **Browser cookies**: Firefox (preferred) or Chrome

### Config file

```json
{
  "authToken": "your_auth_token",
  "ct0": "your_ct0_token"
}
```

### Environment variables

```bash
export X_AUTH_TOKEN="your_auth_token"
export X_CT0="your_ct0_token"
```

## Usage

```bash
# Post
hume-x tweet "Hello world"
hume-x tweet "Check this out" --media photo.jpg --alt "A nice photo"
hume-x reply 1234567890 "Great tweet!"
hume-x quote 1234567890 "Interesting take"
hume-x delete 1234567890

# Read (supports tweet ID or URL)
hume-x read 1234567890
hume-x read https://x.com/user/status/1234567890
hume-x thread 1234567890
hume-x replies 1234567890 -n 50

# Timeline
hume-x home -n 30
hume-x home --following
hume-x home --cursor "abc123" --pages 3
hume-x user-tweets elonmusk -n 10

# Search
hume-x search "typescript" -n 20
hume-x mentions
hume-x mentions --user someuser

# Engage
hume-x like 1234567890
hume-x retweet 1234567890
hume-x bookmark 1234567890
hume-x pin 1234567890

# Lists
hume-x bookmarks
hume-x likes

# Social
hume-x follow username
hume-x unfollow username
hume-x mute username
hume-x block username
hume-x following username
hume-x followers username

# Lists
hume-x lists
hume-x lists --member-of
hume-x list-timeline 1234567890

# Notifications
hume-x notifications

# User info
hume-x whoami
hume-x about elonmusk

# Trending
hume-x trending
hume-x trending --tab news

# Scheduled
hume-x schedule "Future tweet" --at "2025-01-01T12:00:00Z"

# Utility
hume-x check
hume-x query-ids
hume-x refresh-ids
```

Add `--json` to any read command for JSON output, or `--json-full` for the raw API response:

```bash
hume-x home --json | jq '.[0].text'
hume-x home --json-full | jq '.data'
```

## Programmatic Usage

```typescript
import { XClient } from '@humebio/hume-x'

const client = new XClient()
await client.init()

const me = await client.whoami()
console.log(`Logged in as @${me.handle}`)

const tweet = await client.tweet('Hello from hume-x!')
console.log(`Posted: ${tweet.id}`)

const timeline = await client.homeTimeline(10)
for (const t of timeline.items) {
  console.log(`@${t.authorHandle}: ${t.text}`)
}
```

## How It Works

hume-x uses [curl-impersonate](https://github.com/lexiforest/curl-impersonate) (lexiforest fork) for reliable HTTP requests to X's GraphQL API.

Query IDs for GraphQL operations are automatically scraped from x.com's JavaScript bundles and cached locally with a 24-hour TTL. If an ID becomes stale, it automatically rotates to a fallback.

## License

MIT