/xitter

name: xitter
description: Interact with X/Twitter via the x-cli terminal client using official X API credentials. Use for posting, reading timelines, searching tweets, liking, retweeting, bookmarks, mentions, and user lookups.
version: 1.0.0
author: Siddharth Balyan + Zorro Agent
license: MIT
platforms: [linux, macos]
prerequisites:
  commands: [uv]
  env_vars: [X_API_KEY, X_API_SECRET, X_BEARER_TOKEN, X_ACCESS_TOKEN, X_ACCESS_TOKEN_SECRET]
metadata:
  zorro:
    tags: [twitter, x, social-media, x-cli]
    homepage: https://github.com/Infatoshi/x-cli

Xitter — X/Twitter via x-cli

Use `x-cli` for official X/Twitter API interactions from the terminal.

This skill is for:

• posting tweets, replies, and quote tweets
• searching tweets and reading timelines
• looking up users, followers, and following
• liking and retweeting
• checking mentions and bookmarks

This skill intentionally does not vendor a separate CLI implementation into Zorro. Install and use upstream `x-cli` instead.

Important Cost / Access Note

X API access is not meaningfully free for most real usage. Expect to need paid or prepaid X developer access. If commands fail with permissions or quota errors, check your X developer plan first.

Install

Install upstream `x-cli` with `uv`:

uv tool install git+https://github.com/Infatoshi/x-cli.git

Upgrade later with:

uv tool upgrade x-cli

Verify:

x-cli --help

Credentials

You need these five values from the X Developer Portal:

• `X_API_KEY`
• `X_API_SECRET`
• `X_BEARER_TOKEN`
• `X_ACCESS_TOKEN`
• `X_ACCESS_TOKEN_SECRET`

Get them from:

• https://developer.x.com/en/portal/dashboard

Why does X need 5 secrets?

Unfortunately, the official X API splits auth across both app-level and user-level credentials:

• `X_API_KEY` + `X_API_SECRET` identify your app
• `X_BEARER_TOKEN` is used for app-level read access
• `X_ACCESS_TOKEN` + `X_ACCESS_TOKEN_SECRET` let the CLI act as your user account for writes and authenticated actions

So yes — it is a lot of secrets for one integration, but this is the stable official API path and is still preferable to cookie/session scraping.

Setup requirements in the portal: 1. Create or open your app 2. In user authentication settings, set permissions to `Read and write` 3. Generate or regenerate the access token + access token secret after enabling write permissions 4. Save all five values carefully — missing any one of them will usually produce confusing auth or permission errors

Note: upstream `x-cli` expects the full credential set to be present, so even if you mostly care about read-only commands, it is simplest to configure all five.

Cost / Friction Reality Check

If this setup feels heavier than it should be, that is because it is. X’s official developer flow is high-friction and often paid. This skill chooses the official API path because it is more stable and maintainable than browser-cookie/session approaches.

If the user wants the least brittle long-term setup, use this skill. If they want a zero-setup or unofficial path, that is a different trade-off and not what this skill is for.

Where to Store Credentials

`x-cli` looks for credentials in `~/.config/x-cli/.env`.

If you already keep your X credentials in `~/.zorro/.env`, the cleanest setup is:

mkdir -p ~/.config/x-cli
ln -sf ~/.zorro/.env ~/.config/x-cli/.env

Or create a dedicated file:

mkdir -p ~/.config/x-cli
cat > ~/.config/x-cli/.env <<'EOF'
X_API_KEY=your_consumer_key
X_API_SECRET=your_secret_key
X_BEARER_TOKEN=your_bearer_token
X_ACCESS_TOKEN=your_access_token
X_ACCESS_TOKEN_SECRET=your_access_token_secret
EOF
chmod 600 ~/.config/x-cli/.env

Quick Verification

x-cli user get openai
x-cli tweet search "from:NousResearch" --max 3
x-cli me mentions --max 5

If reads work but writes fail, regenerate the access token after confirming `Read and write` permissions.

Common Commands

Tweets

x-cli tweet post "hello world"
x-cli tweet get https://x.com/user/status/1234567890
x-cli tweet delete 1234567890
x-cli tweet reply 1234567890 "nice post"
x-cli tweet quote 1234567890 "worth reading"
x-cli tweet search "AI agents" --max 20
x-cli tweet metrics 1234567890

Users

x-cli user get openai
x-cli user timeline openai --max 10
x-cli user followers openai --max 50
x-cli user following openai --max 50

Self / Authenticated User

x-cli me mentions --max 20
x-cli me bookmarks --max 20
x-cli me bookmark 1234567890
x-cli me unbookmark 1234567890

Quick Actions

x-cli like 1234567890
x-cli retweet 1234567890

Output Modes

Use structured output when the agent needs to inspect fields programmatically:

x-cli -j tweet search "AI agents" --max 5
x-cli -p user get openai
x-cli -md tweet get 1234567890
x-cli -v -j tweet get 1234567890

Recommended defaults:

• `-j` for machine-readable output
• `-v` when you need timestamps, metrics, or metadata
• plain/default mode for quick human inspection

Agent Workflow

1. Confirm `x-cli` is installed 2. Confirm credentials are present 3. Start with a read command (`user get`, `tweet search`, `me mentions`) 4. Use `-j` when extracting fields for later steps 5. Only perform write actions after confirming the target tweet/user and the user's intent

Pitfalls

• **Paid API access**: many failures are plan/permission problems, not code problems.
• **403 oauth1-permissions**: regenerate the access token after enabling `Read and write`.
• **Reply restrictions**: X restricts many programmatic replies. `tweet quote` is often more reliable than `tweet reply`.
• **Rate limits**: expect per-endpoint limits and cooldown windows.
• **Credential drift**: if you rotate tokens in `~/.zorro/.env`, make sure `~/.config/x-cli/.env` still points at the current file.

Notes

• Prefer official API workflows over cookie/session scraping.
• Use tweet URLs or IDs interchangeably — `x-cli` a