x-cli

# x-cli

Full-featured X/Twitter toolkit for OpenClaw agents. Powered by [twikit](https://github.com/d60/twikit) — no API keys required, cookie-based auth.

## Setup

```bash
pip install -r scripts/requirements.txt
cp config.example.json config.json
# Set cookies_file path or credentials in config.json
```

## Commands

### Read (`x_read.py`)
```bash
python scripts/x_read.py tweet <url-or-id>              # Read a tweet
python scripts/x_read.py user <username> --count 5       # User's tweets
python scripts/x_read.py timeline --count 20             # Home timeline (Following)
python scripts/x_read.py foryou --count 20               # For You timeline
python scripts/x_read.py thread <url-or-id>              # Read thread
python scripts/x_read.py replies <url-or-id> --count 20  # Replies to a tweet
python scripts/x_read.py mentions --count 10             # Your mentions
python scripts/x_read.py highlights <username>           # User's highlights
python scripts/x_read.py search-user "query" --count 10  # Search users
```

### Search (`x_search.py`)
```bash
python scripts/x_search.py "query" --count 10
python scripts/x_search.py "from:zerohedge gold" --count 5
```

### Post (`x_post.py`) — confirm with user first!
```bash
python scripts/x_post.py tweet "text"                    # Post tweet
python scripts/x_post.py tweet "text" --media ID1 ID2    # With media
python scripts/x_post.py tweet "text" --dry-run           # Preview only
python scripts/x_post.py reply <id> "text"                # Reply
python scripts/x_post.py quote <id> "text"                # Quote tweet
```

### Interact (`x_interact.py`)
```bash
python scripts/x_interact.py like <tweet>        # Like
python scripts/x_interact.py unlike <tweet>      # Unlike
python scripts/x_interact.py retweet <tweet>     # Retweet
python scripts/x_interact.py unretweet <tweet>   # Undo retweet
python scripts/x_interact.py bookmark <tweet>    # Bookmark
python scripts/x_interact.py unbookmark <tweet>  # Remove bookmark
pyth...

# 𝕏 X-CLI

**X/Twitter toolkit for AI agents — No API key. No developer account. Just cookies.**

An open-source [OpenClaw](https://openclaw.ai) skill that gives AI agents full X/Twitter access. Read tweets, search, post, interact, manage lists, upload media, send DMs — all from the command line.

Powered by [twikit](https://github.com/d60/twikit).

---

## ⚡ Why X-CLI?

| Feature | X-CLI | Twitter API v2 | Bird CLI |
|---------|-------|---------------|----------|
| **Cost** | Free | $100+/mo | Free |
| **API Key** | Not needed | Required | Not needed |
| **Auth** | Cookie-based | OAuth 2.0 | Cookie-based |
| **Status** | ✅ Active | ✅ Active | ⚠️ Deprecated |
| **Server/VPS** | ✅ Works | ✅ Works | ⚠️ Needs browser |
| **Proxy** | ✅ Built-in | N/A | ❌ No |
| **Language** | Python | Any | Node.js |

---

## 📦 Installation

```bash
# Clone the repo
git clone https://github.com/ignsoftwarellc/x-cli.git
cd x-cli

# Install dependencies
pip install -r scripts/requirements.txt

# Create your config
cp config.example.json config.json
```

### 🤖 Or Let Your AI Agent Do It

If you're using an AI agent (OpenClaw, Claude Code, etc.), just say:

> "Install x-cli from https://github.com/ignsoftwarellc/x-cli — my X username is **your_username**, password is **your_password**."

Your agent will clone, install, configure, and authenticate automatically.

---

## 🔐 Authentication

X-CLI uses your browser cookies to authenticate — no API keys needed.

### Option 1: Login with credentials
```bash
python scripts/x_auth.py login --username your_user --password your_pass
# Cookies are saved automatically
```

### Option 2: Use existing cookies
If you already have a `cookies.json` file (e.g. from a browser export), place it in the project root.

### Option 3: Set credentials in config.json
```json
{
  "x_username": "your_username",
  "x_email": "your_email@example.com",
  "x_password": "your_password",
  "cookies_file": "cookies.json",
  "proxy": null,
  "language": "en-US"
}
```...