hume-x

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

Install

# 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

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

Environment variables

export X_AUTH_TOKEN="your_auth_token"
export X_CT0="your_ct0_token"

Usage

# 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:

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

Programmatic Usage

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