twitter-cliSAFE

From the repository's own README, as read at the audited commit. Badges and raw HTML are left out.

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: twitter-cli
description: Use twitter-cli for ALL Twitter/X operations — reading tweets, posting, replying, quoting, liking, retweeting, following, searching, user lookups. Invoke whenever user requests any Twitter interaction.
author: jackwener
version: "0.8.0"
tags:
  - twitter
  - x
  - social-media
  - terminal
  - cli
---

# twitter-cli — Twitter/X CLI Tool

**Binary:** `twitter`
**Credentials:** browser cookies (auto-extracted) or env vars

## Setup

```bash
# Install (requires Python 3.8+)
uv tool install twitter-cli
# Or: pipx install twitter-cli

# Upgrade to latest (recommended to avoid API errors)
uv tool upgrade twitter-cli
# Or: pipx upgrade twitter-cli
```

## Authentication

**IMPORTANT FOR AGENTS**: Before executing ANY twitter-cli command, you MUST first check if credentials exist. If not, you MUST proactively guide the user through the authentication process. Do NOT assume credentials are configured.

**CRITICAL**: Write operations (posting tweets, replying, quoting) REQUIRE full browser cookies. Only providing `auth_token` + `ct0` via env vars may result in **226 error** ("looks like automated behavior"). For best results, use browser cookie extraction.

### Step 0: Check if already authenticated

```bash
twitter status --yaml >/dev/null && echo "AUTH_OK" || echo "AUTH_NEEDED"
```

If `AUTH_OK`, skip to [Command Reference](#command-reference).
If `AUTH_NEEDED`, proceed to guide the user:

### Step 1: Guide user to authenticate

**Method A: Browser cookie extraction (recommended)**

Ensure user is logged into x.com in one of: Arc, Chrome, Edge, Firefox, Brave. twitter-cli auto-extracts cookies.
All Chrome profiles are scanned automatically. To specify a profile: `TWITTER_CHROME_PROFILE="Profile 2" twitter feed`.
To prioritize a specific browser: `TWITTER_BROWSER=chrome twitter feed` (supported: arc, chrome, edge, firefox, brave).

```bash
twitter whoami
```

**Method B: Environment variables**

```bash
export TWITTER_AUTH_TOKEN="<auth_token from browser>"
export TWITTER_CT0="<ct0 from browser>"
twitter whoami
```

**Method C: Full cookie string (for cloud/remote agents)**

Tell the user:

> 我需要你的 Twitter 登录凭证。请按以下步骤获取:
>
> 1. 用 Chrome/Edge/Firefox 打开 https://x.com(确保已登录)
> 2. 按 `F12` 打开开发者工具 → **Network** 标签
> 3. 在页面上刷新,点击任意 `x.com` 请求
> 4. 找到 **Request Headers** → **Cookie:** 这一行,右键 → 复制值
> 5. 把完整 Cookie 字符串发给我
>
> ⚠️ Cookie 包含登录信息,请不要分享给其他人。

Then extract and set env vars:

```bash
FULL_COOKIE="<user's cookie string>"
export TWITTER_AUTH_TOKEN=$(echo "$FULL_COOKIE" | grep -oE 'auth_token=[a-f0-9]+' | cut -d= -f2)
export TWITTER_CT0=$(echo "$FULL_COOKIE" | grep -oE 'ct0=[a-f0-9]+' | cut -d= -f2)
twitter whoami
```

### Step 2: Handle common auth issues

| Symptom | Agent action |
|---------|-------------|
| `No Twitter cookies found` | Guide user to login to x.com in browser, or set env vars |
| Read works, write returns 226 | Full cookies missing — use browser cookie extraction instead of env vars |
| `Cookie expired (401/403)` | Ask user to re-login to x.com and retry |
| User changed password | All old cookies invalidated — re-extract |

## Output Format

### Default: Rich table (human-readable)

```bash
twitter feed                          # Pretty table output
```

### YAML / JSON: structured output

Non-TTY stdout defaults to YAML automatically. Use `OUTPUT=yaml|json|rich|auto` to override.

```bash
twitter feed --yaml
twitter feed --json | jq '.[0].text'
```

All machine-readable output uses the envelope documented in [SCHEMA.md](./SCHEMA.md).
Tweet and user payloads now live under `.data`.

### Full text: `--full-text` flag (rich tables only)

Use `--full-text` when the user wants complete post bodies in terminal tables.
It affects rich table list views such as `feed`, `bookmarks`, `search`, `user-posts`, `likes`, `list`, and reply tables in `tweet`.
It does **not** change `--json`, `--yaml`, or `-c` compact output.

```bash
twitter feed --full-text
twitter search "AI agent" --full-text
twitter user-posts elonmusk --max 20 --full-text
twitter tweet 1234567890 --full-text
```

### Compact: `-c` flag (minimal tokens for LLM)

```bash
twitter -c feed --max 10              # Minimal fields, great for LLM context
twitter -c search "AI" --max 20       # ~80% fewer tokens than --json
```

**Compact fields (per tweet):** `id`, `author` (@handle), `text` (truncated 140 chars), `likes`, `rts`, `time` (short format)

## Command Reference

### Read Operations

```bash
twitter status                         # Quick auth check
twitter status --yaml                  # Structured auth status
twitter whoami                         # Current authenticated user
twitter whoami --yaml                  # YAML output
twitter whoami --json                  # JSON output
twitter user elonmusk                  # User profile
twitter user elonmusk --json           # JSON output
twitter feed                           # Home timeline (For You)
twitter feed -t following              # Following timeline
twitter feed --max 50                  # Limit count
twitter feed --full-text               # Show full post body in table
twitter feed --filter                  # Enable ranking filter
twitter feed --yaml > tweets.yaml      # Export as YAML
twitter feed --input tweets.json       # Read from local JSON file
twitter bookmarks                      # Bookmarked tweets
twitter bookmarks --full-text          # Full text in bookmarks table
twitter bookmarks --max 30 --yaml
twitter search "keyword"               # Search tweets
twitter search "AI agent" -t Latest --max 50
twitter search "AI agent" --full-text  # Full text in search results
twitter search "topic" -o results.json # Save to file
twitter tweet 1234567890               # Tweet detail + replies
twitter tweet 1234567890 --full-text   # Full text in reply table
twitter tweet https://x.com/user/status/12345  # Accepts URL
twitter show 2                         # Open tweet #2 from last feed/search list
twitter show 2 --full-text  

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (3)

export TWITTER_PROXY=http://127.0.0.1:7890

export TWITTER_PROXY=http://127.0.0.1:7890

- **Local terminal**: Open **Keychain Access** → search for **"\<Browser\> Safe Storage"** → **Access Control** → add your Terminal app → **Save Changes**.

Gates applied: no_behavioural_pass.

[![ModelsAtlas audit: twitter-cli](https://modelsatlas.com/skills/jackwener/twitter-cli/badge.svg)](https://modelsatlas.com/skills/jackwener/twitter-cli/)

Not your listing, or something out of date? Claim or update your listing.