TwitterAPI CLI

A token-efficient CLI tool for retrieving Twitter data via TwitterAPI.io. Filters API responses to reduce token usage by 70-90% compared to full responses.

Quick Start

# Get user profile (compact output)
twitterapi user info elonmusk --compact

# Get recent tweets
twitterapi user tweets elonmusk --limit 10 --compact

# Search for tweets
twitterapi tweet search "AI tools" --limit 20 --compact

# Get followers
twitterapi user followers elonmusk --limit 50

# Get following
twitterapi user following elonmusk --limit 50

Command Overview

Command	Description	Key Options
user info <username>	User profile	--compact, --fields
user tweets <username>	User timeline	--limit, --include-replies, --compact, --fields
user followers <username>	Follower list	--limit, --compact
user following <username>	Following list	--limit, --compact
tweet search <query>	Search tweets	--limit, --compact, --fields

Full reference: See references/cli.md for complete command documentation.

Field Filtering

The CLI's core feature is field filtering - extracting only the data you need from API responses.

Using Compact Mode

# Use preset field sets (saves 70-90% tokens)
twitterapi user info elonmusk --compact
twitterapi user tweets elonmusk --limit 10 --compact
twitterapi tweet search "AI tools" --compact

Custom Fields

# Specify exact fields with dot notation
twitterapi user info elonmusk --fields "id,name,description,verified"

# Nested fields use dots
twitterapi user tweets elonmusk --fields "id,text,public_metrics.like_count,public_metrics.retweet_count"

Complete guide: See references/fields.md for all presets, dot notation syntax, and examples.

Output Format

All commands return JSON to stdout for easy parsing.

Success:

{
  "id": "123456",
  "screen_name": "elonmusk",
  "name": "Elon Musk",
  "followers_count": 150000000
}

Error:

{
  "error": true,
  "type": "api_error",
  "message": "User not found",
  "status_code": 404
}

Configuration

Set your API key via environment variable:

export TWITTERAPI_KEY="your-api-key-here"

Or create ~/.twitterapi/config.json:

{
  "api_key": "your-api-key",
  "base_url": "https://api.twitterapi.io",
  "timeout": 30
}

Usage Patterns

User Profile Analysis

# Get compact profile
twitterapi user info elonmusk --compact

# Get specific metrics
twitterapi user info elonmusk --fields "id,name,followers_count,verified"

Tweet Engagement Analysis

# Get tweets with engagement metrics
twitterapi user tweets elonmusk --limit 20 --compact

# Custom engagement fields
twitterapi user tweets elonmusk --limit 50 --fields "id,text,created_at,public_metrics.like_count,public_metrics.retweet_count"

Follower/Following Analysis

# Get follower list (compact)
twitterapi user followers elonmusk --limit 100

# Get following list
twitterapi user following elonmusk --limit 100

Content Search

# Search for specific topics
twitterapi tweet search "machine learning" --limit 50 --compact

# Search with custom fields
twitterapi tweet search "openai" --limit 20 --fields "id,text,created_at,author_id"

Error Handling

The CLI exits with status code 1 on API errors and outputs structured JSON to stderr:

{
  "error": true,
  "type": "api_error",
  "message": "Error description",
  "command": "user info",
  "status_code": 404
}

Common errors:

• 401 - Invalid API key
• 404 - User not found
• 429 - Rate limit exceeded
• 500 - API server error

Related Documentation

• CLI Command Reference: references/cli.md - Complete command and option documentation
• Field Filtering Guide: references/fields.md - Presets, dot notation, and examples
• API Endpoints: https://docs.twitterapi.io/skill.md - Original API skill with detailed endpoint documentation

Technical Notes

• Executable: scripts/twitterapi - Standalone Bun binary
• Runtime: No external dependencies (bundled)
• Output: JSON only (designed for agent/AI consumption)
• Token Savings: 70-90% reduction with field filtering
• Rate Limits: Handled automatically (retry after delay)

Building from Source

Source code is located in the cli/ directory. To compile the executable:

Prerequisites

• Bun runtime installed

Build Steps

# Navigate to source directory
cd cli

# Install dependencies
bun install

# Compile for current platform
bun build src/index.ts --compile --outfile ../scripts/twitterapi

# Or compile for specific platform
# Linux x64: bun build src/index.ts --compile --target bun-linux-x64 --outfile ../scripts/twitterapi
# macOS ARM64: bun build src/index.ts --compile --target bun-darwin-arm64 --outfile ../scripts/twitterapi

Build Targets

Platform	Target Flag
Linux x64	--target bun-linux-x64
Linux ARM64	--target bun-linux-arm64
macOS x64	--target bun-darwin-x64
macOS ARM64	--target bun-darwin-arm64
Windows x64	--target bun-windows-x64

The compiled binary is a standalone executable with no external dependencies.