xitter

name	xitter
description	Post, read, and search X (Twitter) content using x-cli or the X API v2
category	social
version	1.0.0
origin	aiden
license	Apache-2.0
tags	twitter, x, social-media, tweet, post, search, api, x-cli, timeline, mentions

X (Twitter) Automation

Read, post, and search X content using the x-cli command-line tool or the X API v2 directly. Requires X API credentials.

When to Use

• User wants to post a tweet or thread on X
• User wants to search for recent tweets on a topic
• User wants to read their home timeline or mentions
• User wants to fetch tweets from a specific account
• User wants to schedule or automate social media posts

How to Use

1. Set up X API credentials

Register at https://developer.twitter.com → Create Project → Create App. Get:

• API_KEY, API_SECRET
• ACCESS_TOKEN, ACCESS_TOKEN_SECRET
• BEARER_TOKEN (for read-only app-only auth)

$env:X_BEARER_TOKEN      = "your_bearer_token"
$env:X_API_KEY           = "your_api_key"
$env:X_API_SECRET        = "your_api_secret"
$env:X_ACCESS_TOKEN      = "your_access_token"
$env:X_ACCESS_SECRET     = "your_access_secret"

2. Search recent tweets (Bearer Token — no user auth needed)

import requests, os

def search_tweets(query, max_results=10):
  headers = {"Authorization": f"Bearer {os.environ['X_BEARER_TOKEN']}"}
  params  = {
    "query":        f"{query} -is:retweet lang:en",
    "max_results":  max_results,
    "tweet.fields": "created_at,author_id,public_metrics"
  }
  resp = requests.get("https://api.twitter.com/2/tweets/search/recent", headers=headers, params=params)
  resp.raise_for_status()
  for tweet in resp.json().get("data", []):
    print(f"• {tweet['text'][:120]}")
    print(f"  {tweet['created_at']}  likes={tweet['public_metrics']['like_count']}\n")

search_tweets("Aiden AI agent 2026", max_results=5)

3. Post a tweet (OAuth 1.0a)

import requests, os, time, hashlib, hmac, base64, urllib.parse, uuid

def post_tweet(text):
  url    = "https://api.twitter.com/2/tweets"
  params = {"text": text}

  # OAuth 1.0a signature
  oauth_params = {
    "oauth_consumer_key":     os.environ["X_API_KEY"],
    "oauth_nonce":            uuid.uuid4().hex,
    "oauth_signature_method": "HMAC-SHA1",
    "oauth_timestamp":        str(int(time.time())),
    "oauth_token":            os.environ["X_ACCESS_TOKEN"],
    "oauth_version":          "1.0",
  }
  signing_key  = "&".join([urllib.parse.quote(os.environ["X_API_SECRET"], safe=""),
                            urllib.parse.quote(os.environ["X_ACCESS_SECRET"], safe="")])
  base_string  = "&".join(["POST", urllib.parse.quote(url, safe=""),
                            urllib.parse.quote("&".join(f"{k}={v}" for k,v in sorted(oauth_params.items())), safe="")])
  signature    = base64.b64encode(hmac.new(signing_key.encode(), base_string.encode(), hashlib.sha1).digest()).decode()
  oauth_params["oauth_signature"] = signature

  auth_header  = "OAuth " + ", ".join(f'{k}="{urllib.parse.quote(v, safe="")}"' for k,v  oauth_params.items())
  resp = requests.post(url, json=params, headers={: auth_header, : })
  resp.raise_for_status()
  ()

post_tweet()

4. Fetch user timeline

import requests, os

def get_user_timeline(username, max_results=10):
  headers = {"Authorization": f"Bearer {os.environ['X_BEARER_TOKEN']}"}
  user    = requests.get(f"https://api.twitter.com/2/users/by/username/{username}", headers=headers).json()
  user_id = user["data"]["id"]

  resp    = requests.get(
    f"https://api.twitter.com/2/users/{user_id}/tweets",
    headers=headers,
    params={"max_results": max_results, "tweet.fields": "created_at,public_metrics", "exclude": "retweets"}
  )
  for tweet in resp.json().get("data", []):
    print(f"• {tweet['text'][:120]}\n  {tweet['created_at']}\n")

get_user_timeline("elonmusk", max_results=5)

5. Read mentions

import requests, os

def get_mentions(user_id, max_results=10):
  headers = {"Authorization": f"Bearer {os.environ['X_BEARER_TOKEN']}"}
  resp    = requests.get(
    f"https://api.twitter.com/2/users/{user_id}/mentions",
    headers=headers,
    params={"max_results": max_results, "tweet.fields": "created_at,author_id"}
  )
  for tweet in resp.json().get("data", []):
    print(f"• {tweet['text'][:120]}\n  {tweet['created_at']}\n")

Examples

"Search for recent tweets about LLM agents" → Use step 2 with query "LLM agents".

"Post a tweet saying 'Aiden just automated my morning report'" → Ask user to confirm before posting, then use step 3.

"Show me the last 10 tweets from a specific account" → Use step 4 with the target username.

Cautions

• Posting tweets requires user-context OAuth 1.0a — Bearer Token alone cannot post
• X API free tier limits search results to the last 7 days and 1 request per 15 minutes
• Always ask user for explicit confirmation before posting any tweet on their behalf
• X API rate limits are strict — cache results locally rather than re-fetching on every call
• Never hardcode API credentials — always use environment variables