# twitter

> Fetch Twitter/X likes and bookmarks. Use when asked to download liked tweets, get Twitter bookmarks, or fetch saved tweets from X.

- Author: Hamel Husain
- Repository: hamelsmu/hamel
- Version: 20260123162814
- Stars: 46
- Forks: 0
- Last Updated: 2026-02-06
- Source: https://github.com/hamelsmu/hamel
- Web: https://mule.run/skillshub/@@hamelsmu/hamel~twitter:20260123162814

---

---
name: twitter
description: Fetch Twitter/X likes and bookmarks. Use when asked to download liked tweets, get Twitter bookmarks, or fetch saved tweets from X.
---

# Twitter/X Likes and Bookmarks

Use the `twitter` CLI tool to fetch your liked and bookmarked tweets using browser cookies (no API credits required).

## Setup

### Automated Setup (Recommended)

Use `agent-browser` to login and automatically extract cookies:

```bash
twitter refresh
```

This opens a browser window where you can log in (including 2FA). Cookies are extracted automatically after successful login.

### Manual Setup

Alternatively, get cookies manually from your browser:

1. Log into https://x.com in your browser
2. Open Developer Tools (F12) → Application → Cookies → x.com
3. Copy the values for **ct0** and **auth_token**
4. Run setup:

```bash
twitter setup
```

Or manually create `~/.twitter_cookies.json`:
```json
{"ct0": "your_ct0_value", "auth_token": "your_auth_token_value"}
```

> ⚠️ **Security**: Never save cookies inside a git repository. The default location (`~/.twitter_cookies.json`) is outside your repo. If you use `--path`, ensure the file is in `.gitignore`.

## Usage

### Fetch Likes

```bash
# Output liked tweets to stdout as JSON (requires TWITTER_USERNAME env var or --username)
twitter likes -u myusername

# Save to a file
twitter likes -u myusername -o likes.json

# Limit to most recent 50 likes
twitter likes -u myusername -n 50 -o recent-likes.json

# Verbose mode shows progress
twitter likes -u myusername -v -o all-likes.json

# Auto-refresh cookies if expired (opens browser for login)
twitter likes -u myusername --auto-refresh -o likes.json

# Raw API response (for debugging)
twitter likes -u myusername --raw -n 5
```

### Fetch Bookmarks

```bash
# Output bookmarks to stdout as JSON
twitter bookmarks

# Save to a file
twitter bookmarks -o bookmarks.json

# Limit number of bookmarks
twitter bookmarks -n 100 -o bookmarks.json

# Auto-refresh if cookies are expired
twitter bookmarks --auto-refresh -v -o bookmarks.json
```

## Commands

| Command | Description |
|---------|-------------|
| `twitter refresh` | Automated cookie refresh via browser (recommended) |
| `twitter setup` | Manual interactive setup to save cookies |
| `twitter likes` | Fetch your liked tweets |
| `twitter bookmarks` | Fetch your bookmarked tweets |
| `twitter screenshot` | Take a screenshot of a tweet |

## Options

| Option | Short | Description |
|--------|-------|-------------|
| `--output` | `-o` | Output file path (default: stdout) |
| `--limit` | `-n` | Maximum number of tweets to fetch |
| `--verbose` | `-v` | Show progress information |
| `--auto-refresh` | `-a` | Auto-refresh cookies via browser if expired |
| `--username` | `-u` | Twitter username (likes command only, or set TWITTER_USERNAME) |
| `--raw` | | Output raw API response |
| `--full-page` | `-f` | Capture full page (screenshot only) |
| `--wait` | `-w` | Seconds to wait for page load (screenshot only) |

## Output Format

Returns JSON array of tweet objects:

```json
[
  {
    "id": "1234567890",
    "text": "Tweet content here...",
    "created_at": "Fri Jan 23 20:01:07 +0000 2026",
    "author": {
      "id": "987654321",
      "username": "example_user",
      "name": "Example User"
    },
    "metrics": {
      "like_count": 100,
      "retweet_count": 10,
      "reply_count": 5,
      "quote_count": 2
    },
    "url": "https://x.com/example_user/status/1234567890"
  }
]
```

## Environment Variables

- `TWITTER_USERNAME` - Your Twitter username for likes lookup (required for `likes` command unless using `--username`)
- `TWITTER_COOKIES_FILE` - Path to cookies file (default: `~/.twitter_cookies.json`)

## Requirements

The `hamel` package must be installed: `pip install hamel`

### Optional Dependencies

**For `twitter refresh` (automated cookie extraction):**
```bash
npm install -g agent-browser
# Or use via npx (no install needed): npx agent-browser
```
See the [agent-browser skill](https://skills.sh/vercel-labs/agent-browser/agent-browser) for more details.

**For `twitter screenshot`:**
```bash
pip install playwright && playwright install chromium
```

## Examples

**Download all likes and analyze with AI:**
```bash
twitter likes -u myusername -o /tmp/likes.json
ai-gem "What topics am I most interested in based on my likes?" /tmp/likes.json
```

**Get recent bookmarks for reference:**
```bash
twitter bookmarks -n 20 -v
```

**Export all bookmarks:**
```bash
twitter bookmarks -o ~/bookmarks-backup.json -v
```

### Screenshot a Tweet

```bash
# Screenshot a tweet (saves to tweet_<id>.png)
twitter screenshot https://x.com/user/status/1234567890

# Save to specific file
twitter screenshot https://x.com/user/status/1234567890 -o my_tweet.png

# Full page screenshot
twitter screenshot https://x.com/user/status/1234567890 --full-page

# Wait longer for slow loading tweets
twitter screenshot https://x.com/user/status/1234567890 --wait 5 -v
```

## Troubleshooting

**"Cookies file not found"**: Run `twitter refresh` (automated) or `twitter setup` (manual) to configure authentication.

**Empty results or auth errors**: Your cookies may have expired. Use `--auto-refresh` flag to automatically refresh, or run `twitter refresh` manually.

**Rate limiting**: The tool uses Twitter's internal API. If you hit rate limits, wait a few minutes before retrying.

**agent-browser not found**: Install with `npm install -g agent-browser` or use via `npx agent-browser` for automated cookie refresh.

**playwright not installed**: For screenshots, install with `pip install playwright && playwright install chromium`.