Skip to main content

​
Overview

twitter-cli ships with a SKILL.md file that teaches AI agents how to use the CLI for common Twitter/X workflows. This enables agents to read timelines, search tweets, fetch user data, and post content autonomously.

​
What is a Skill?

A skill is a structured markdown file that provides:
  • Command reference and examples
  • Authentication setup instructions
  • Common patterns and workflows
  • Error handling guidance
  • Safety notes for rate limiting and anti-detection
When an AI agent has access to the skill file, it can execute Twitter operations more reliably without needing to guess command syntax or flags.

​
Installation

​
Claude Code / Antigravity

Clone the entire repository into your project’s .agents/skills directory: 
# Create skills directory
mkdir -p .agents/skills

# Clone full repository
git clone [email protected]:jackwener/twitter-cli.git .agents/skills/twitter-cli
Or download just the SKILL.md file: 
# Create skill directory
mkdir -p .agents/skills/twitter-cli

# Download SKILL.md only
curl -o .agents/skills/twitter-cli/SKILL.md \
  https://raw.githubusercontent.com/jackwener/twitter-cli/main/SKILL.md
Claude Code will automatically detect and load skills from .agents/skills/*/SKILL.md.

​
OpenClaw / ClawHub

Install via ClawHub package manager: 
clawhub install twitter-cli
After installation, OpenClaw can invoke twitter-cli commands directly based on the skill instructions.

​
Other AI Agents

For custom AI agents or frameworks:
  1. Download the skill file: 
    curl -O https://raw.githubusercontent.com/jackwener/twitter-cli/main/SKILL.md
  2. Include it in your agent’s context or prompt directory
  3. Configure your agent to reference the skill when the user mentions Twitter/X tasks

​
Skill Contents

The SKILL.md file includes:

​
Metadata

---
name: twitter-cli
description: CLI skill for Twitter/X to read timelines, bookmarks, user posts, and profiles from the terminal without API keys
author: jackwener
version: "1.0.0"
tags:
  - twitter
  - x
  - social-media
  - terminal
  - cli
---

​
Command Reference

Complete examples for:
  • Feed (For You / Following timelines)
  • Bookmarks
  • Search (Top / Latest / Photos / Videos)
  • Tweet detail
  • List timeline
  • User profiles and posts
  • Write operations (post, like, retweet, bookmark)

​
Authentication Guidance

  • Browser cookie extraction (recommended)
  • Environment variable setup
  • Error handling for expired cookies

​
JSON / Scripting Patterns

twitter feed --json > tweets.json
twitter feed --input tweets.json
twitter user-posts elonmusk --json | jq '.[0].text'

​
Ranking Filter

Documentation on the optional --filter flag and scoring formula.

​
Common Patterns for AI Agents

# Get latest tweets from a user
twitter user-posts elonmusk --max 5 --json

# Search and export for analysis
twitter search "topic" --json > results.json

# Check user profile
twitter user elonmusk --json

# Daily reading workflow
twitter feed -t following --filter
twitter favorites --filter

​
Error Handling

  • No Twitter cookies found - login to x.com in a supported browser
  • Cookie expired or invalid (HTTP 401/403) - re-login and retry
  • Twitter API error 404 - queryId rotation, retry the command

​
Safety Notes

  • Write operations have built-in delays (1.5-4s)
  • TLS fingerprint and User-Agent are automatically matched
  • Never share raw cookie values in chat logs
  • Prefer browser cookie extraction over manual entry
  • If auth fails, ask user to re-login to x.com

​
Agent Workflows

​
Example 1: Research Workflow

User prompt:
“Research what AI researchers are saying about Claude Code”
Agent execution: 
# Search for recent tweets
twitter search "Claude Code" -t Latest --max 30 --json > claude_code_research.json

# Extract key insights using jq
cat claude_code_research.json | jq '.[] | {author: .author.screenName, text: .text, likes: .metrics.likes}' | head -20

​
Example 2: User Analysis

User prompt:
“Analyze @elonmusk’s recent tweets and find the most engaging ones”
Agent execution: 
# Fetch recent posts
twitter user-posts elonmusk --max 50 --json > elon_tweets.json

# Apply ranking filter
twitter feed --input elon_tweets.json --filter

# Get top 5 by engagement
cat elon_tweets.json | jq 'sort_by(.metrics.likes + .metrics.retweets) | reverse | .[0:5]'

​
Example 3: Content Monitoring

User prompt:
“Monitor mentions of our product and save high-engagement tweets”
Agent execution: 
# Search for product mentions
twitter search "YourProduct" --max 100 --json > mentions.json

# Filter high engagement (>50 likes)
cat mentions.json | jq '[.[] | select(.metrics.likes > 50)]' > high_engagement.json

# Display results
twitter feed --input high_engagement.json

​
Example 4: Automated Posting

User prompt:
“Post a thread about today’s product updates”
Agent execution: 
# Post first tweet
twitter post "Excited to announce our new feature! 🚀 Thread 👇"

# Wait for response to get tweet ID, then reply
twitter post "1/ First, we've added real-time collaboration..." --reply-to <TWEET_ID>

twitter post "2/ Second, performance improvements across the board..." --reply-to <PREVIOUS_ID>

​
Prerequisites

The skill assumes twitter-cli is already installed. Agents should verify installation: 
# Check if twitter-cli is installed
which twitter

# If not installed, recommend installation
uv tool install twitter-cli
# or
pipx install twitter-cli

​
Security Considerations

  1. Cookie Safety: The skill instructs agents to never ask users to share raw cookie values in chat logs
  2. Browser Extraction: Agents should prefer automatic browser cookie extraction over manual entry
  3. Proxy Awareness: Agents should respect TWITTER_PROXY environment variable if set
  4. Rate Limiting: Agents should use --max flags conservatively to avoid rate limits
  5. Write Delays: The skill notes that write operations automatically include 1.5-4s delays

​
Updating the Skill

To update to the latest skill version: 
# If using git clone
cd .agents/skills/twitter-cli
git pull

# If using curl
curl -o .agents/skills/twitter-cli/SKILL.md \
  https://raw.githubusercontent.com/jackwener/twitter-cli/main/SKILL.md

​
Skill Development

If you want to customize the skill for your team:
  1. Fork the repository
  2. Edit SKILL.md to add team-specific workflows
  3. Point your agents to your custom skill location
Example custom additions: 
## Team-Specific Workflows

### Daily Standup Post
```bash
twitter post "Daily update: $(cat standup.txt)"

​
Competitor Monitoring

twitter search "CompetitorName" -t Latest --max 20 --json > competitor.json


## Troubleshooting

### Agent Not Finding Skill

- Verify the skill file is at `.agents/skills/twitter-cli/SKILL.md`
- Check file permissions: `chmod 644 .agents/skills/twitter-cli/SKILL.md`
- Restart your AI agent to reload skills

### Agent Executing Wrong Commands

- Review the skill file to ensure command syntax is correct
- Update to the latest version of the skill
- File an issue at https://github.com/jackwener/twitter-cli/issues

### Authentication Failures

- Agent should prompt user to login to x.com
- Verify browser is supported (Chrome/Edge/Firefox/Brave)
- Try setting `TWITTER_AUTH_TOKEN` and `TWITTER_CT0` manually as fallback

Build docs developers (and LLMs) love

Get started for freeTalk to us