git:20260408.d201033 to git:20260801.3cb01ce

+ Skill for reading and writing Twitter/X data with Python + UV, with zero third-party dependencies (pure standard library), by directly passing

+ the auth_token + ct0 cookies for authentication. In the Minis environment, cookies can be retrieved automatically with the browser_use tool

+ by navigating to x.com and then using the get_cookies action, with no manual copying required. Supports scraping the home timeline, following list,

+ bookmarks (including bookmark folders), search, user profiles, user tweets, likes, tweet details (single tweet or with replies), List timelines,

+ followers/following lists, and write operations such as posting, deleting, liking, retweeting, and bookmarking. This skill must be triggered when the user mentions "scraping Twitter data,"

+ "get X tweets," "Twitter timeline," "X bookmarks," "search tweets," "twitter-x-hub,"

+ "request Twitter with cookies," "Twitter GraphQL," or any scenario that requires programmatic reading or writing of Twitter/X

+ data.

+ > **Modified from**: [public-clis/twitter-cli](https://github.com/public-clis/twitter-cli) (formerly jackwener/twitter-cli)

+ > This skill simplifies the original repository as follows: it removes the `browser-cookie3`/`rich`/`click`/`PyYAML`/`curl_cffi`/

+ > `xclienttransaction`/`beautifulsoup4` dependencies and replaces them with a pure standard library implementation; authentication now uses directly supplied cookies

+ > instead of automatic browser extraction; Twitter Article rendering and image upload functionality have been removed.

+ ## File Structure

+ ├── pyproject.toml # UV project configuration (zero third-party dependencies)

+ ├── models.py # Data models (Tweet, Author, Metrics, UserProfile, BookmarkFolder)

+ ├── parser.py # GraphQL response parsing (split from client.py, synced from upstream v0.8.6)

+ ├── client.py # GraphQL client (core logic)

+ └── cli.py # Command-line entry point (argparse)

+ ## Authentication

+ The Twitter/X internal GraphQL API uses two cookies for authentication:

+ | Cookie | Description |

+ |--------|-------------|

+ | `auth_token` | User login credential (OAuth Session Token) |

+ | `ct0` | CSRF Token, also used as the `X-Csrf-Token` request header |

+ ### Method 1: Retrieve automatically with the `browser_use` tool (recommended, preferred in the Minis environment)

+ In Minis, you can use the `browser_use` tool to navigate directly to x.com, then use the `get_cookies` action to read cookies,

+ with no manual copying required. **After retrieval, store them in environment variables immediately** to avoid exposing plaintext values in the conversation context.

+ Steps:

+ 1. Use `browser_use navigate` to open `https://x.com` and confirm you are logged in.

+ 2. Use `browser_use get_cookies` to retrieve all cookies.

+ - The tool returns an offload env file path, such as `/var/minis/offloads/env_cookies_xxx.sh`.

+ - **Raw cookie values will not appear in the conversation.**

+ 3. Load the file, then use the cookies:

+ ### Method 2: Set environment variables manually

+ Copy `auth_token` and `ct0` from browser DevTools -> Application -> Cookies -> `https://x.com`,

+ then store them in Minis environment variables (Settings -> Environments): `TWITTER_AUTH_TOKEN` + `TWITTER_CT0`

+ ### Passing credentials (three methods, in descending priority)

+ 1. Environment variables: `TWITTER_AUTH_TOKEN` + `TWITTER_CT0` (recommended)

+ 2. CLI parameters: `--auth-token <value> --ct0 <value>`

+ 3. Pass directly in code: `TwitterClient(auth_token=..., ct0=...)`

+ ## Quick Start

+ ### Environment Setup

+ # Confirm UV is available

+ # Enter the skill directory

+ ### CLI Usage

+ # Scrape the home For-You timeline (20 items by default)

+ # Scrape the Following timeline, 30 items, JSON output

+ # Search tweets (Top/Latest/Photos/Videos)

+ # Bookmarks

+ # Bookmark folder list (new)

+ # User profile

+ # User tweets

+ # User likes

+ # Tweet details (including reply thread)

+ # Quickly retrieve a single tweet (new, faster than the tweet command)

+ # List timeline

+ # Followers / following lists (first use the user command to get user_id)

+ # Post a tweet / reply

+ # Like / retweet / bookmark

+ ### Use environment variables to avoid passing credentials each time

+ ### Call as a Python library

+ # Scrape the home timeline

+ # Search (Latest tab)

+ # Single tweet (quick, no replies)

+ # Bookmark folders

+ # User profile

+ # JSON serialization

+ ## Core Implementation Principles

+ ### Authentication Mechanism

+ Uses browser cookies (`auth_token` + `ct0`) plus a hard-coded public Bearer Token

+ to impersonate a Chrome browser request to Twitter's internal GraphQL API.

+ ### Three-level QueryId resolution (automatically handles API changes)

+ 1. In-memory cache (fastest)

+ 2. Hard-coded FALLBACK_QUERY_IDS (constant fallback)

+ → If 404, the queryId has expired; proceed to the next level

+ 3. Fetch the latest queryId from github.com/fa0311/twitter-openapi

+ → If it is still unavailable, scan the x.com JS Bundle and extract it with a regular expression

+ ### URL Optimization (synced from upstream v0.8)

+ - Keys with a value of `False` in the `features` dictionary are not sent, avoiding overly long URLs (414 errors).

+ ### Pagination & Rate Limiting

+ - Each response includes a `cursor`; pages are fetched automatically until the `count` limit is reached.

+ - The default request interval is 1.5 seconds + ±30% random jitter. HTTP 429 triggers exponential backoff and retry.

+ - Write operations use a random delay of 1.5 to 4 seconds.

+ ### Parser Split (synced from upstream v0.7+)

+ - `parser.py` was split out from `client.py` and includes independent functions such as `parse_tweet_result`, `parse_timeline_response`,

+ and `parse_user_result`, making unit testing and reuse easier.

+ ## CLI Subcommand Quick Reference

+ | Subcommand | Description | Key Parameters |

+ |------------|-------------|----------------|

+ | `feed` | Home timeline | `--type for-you\|following`, `--max`, `--json` |

+ | `bookmarks` | Bookmarks | `--max`, `--json` |

+ | `bookmark-folders` | Bookmark folder list ⭐ New | `--json` |

+ | `search` | Search | `query`, `--tab Top\|Latest\|Photos\|Videos`, `--max`, `--json` |

+ | `user` | User profile | `screen_name`, `--json` |

+ | `user-posts` | User tweets | `screen_name`, `--max`, `--json` |

+ | `user-likes` | User likes | `screen_name`, `--max`, `--json` |

+ | `tweet` | Tweet details + replies | `tweet_id`, `--max`, `--json` |

+ | `tweet-by-id` | Single tweet (quick) ⭐ New | `tweet_id`, `--json` |

+ | `list` | List timeline | `list_id`, `--max`, `--json` |

+ | `followers` | Followers list | `user_id`, `--max`, `--json` |

+ | `following` | Following list | `user_id`, `--max`, `--json` |

+ | `post` | Post a tweet | `text`, `--reply-to` |

+ | `delete` | Delete a tweet | `tweet_id` |

+ | `like` / `unlike` | Like/unlike | `tweet_id` |

+ | `retweet` / `unretweet` | Retweet/unretweet | `tweet_id` |

+ | `bookmark` / `unbookmark` | Bookmark/unbookmark | `tweet_id` |

+ All subcommands support the `--auth-token` / `--ct0` parameters, which can also be replaced with environment variables.

+ ## Change Log (synced from upstream)

+ ### v0.8.6 Sync (2026-04-08)

+ - **Full QueryId update**: Real-time scanning from the x.com JS bundle (main.0e98bc8a.js) updated

+ all IDs, including HomeTimeline, HomeLatestTimeline, UserTweets, SearchTimeline, Likes, TweetDetail,

+ TweetResultByRestId, ListLatestTweetsTimeline, Followers, Following, CreateTweet, and others.

+ - **New QueryIds**: `TweetResultByRestId`, `BookmarkFoldersSlice`, `BookmarkFolderTimeline`

+ - **New commands**: `tweet-by-id` (quick single-tweet retrieval), `bookmark-folders` (bookmark folders)

+ - **models.py**: Added the `bookmarks` field to `Metrics`; added the `article_title`,

+ `article_text`, and `is_subscriber_only` fields to `Tweet`; added the `BookmarkFolder` dataclass.

+ - **parser.py**: Split from `client.py` into an independent module; fixed the new API structure (`core.name`/`core.screen_name`);

+ `parse_tweet_result` supports full text from `note_tweet` (long tweets with "Show more");

+ added `_unwrap_visibility` to handle `TweetWithVisibilityResults`;

+ fixed `parse_user_result` so the `joined` date is read from `core.created_at`.

+ - **URL optimization**: `False` values in `features` are not sent, avoiding 414 errors.

+ - **SearchTimeline restriction**: Starting in late 2025, X requires the `x-client-transaction-id` header.

+ This header is generated by `xclienttransaction` (a C extension), which cannot be installed in the iSH/Alpine environment.

+ Therefore, the `search` command is temporarily unavailable in this environment. Alternative: use `browser_use` to navigate to the search page and extract the DOM.

+ ## Notes

+ - Cookies are typically valid for several weeks to several months. After they expire, they must be retrieved from the browser again.

+ - Use a dedicated secondary account to reduce the risk of your main account being flagged by risk controls.

+ - Write operations, such as posting tweets and liking tweets, carry a higher risk of triggering risk controls than read operations. Use them at your discretion.

+ - `max_count` has a hard limit of 500 to prevent accidentally sending a large number of requests.

+ - Upstream uses `curl_cffi` for TLS fingerprint spoofing. This skill uses stdlib `urllib` instead.

+ If you encounter risk controls, you can try passing the complete cookie string through the `cookie_string` parameter to strengthen the fingerprint.