Tech Twitter CLI

Every Tech Twitter read endpoint, plus an offline-searchable local mirror and cited evidence bundles no other tool has.

Tech Twitter curates, dedupes, summarizes, and quality-scores the high-signal slice of tech X. This CLI turns that into a local SQLite mirror you can full-text search offline, and adds commands that only a compounding store can answer: what changed since your last sync, topic momentum over time, emerging narratives, time travel to any past day, and offline cited evidence bundles for agents.

Quick Start

# Confirm the CLI and its reachability config before anything else.
techtwitter-pp-cli doctor --dry-run

# Pull the curated stream into the local SQLite mirror.
techtwitter-pp-cli sync

# Full-text search the curated corpus offline.
techtwitter-pp-cli search "agents"

# Pull the live ranked trending stream as JSON.
techtwitter-pp-cli tweets trending --limit 5 --json

# Compose an offline read-list for the last 24 hours.
techtwitter-pp-cli digest --window 24h --agent

Unique Features

These capabilities aren't available in any other tool for this API.

Local state that compounds

• since — See only the tweets curated or newly hot since your last sync, instead of re-reading the whole stream.

  Reach for this to answer "what did I miss" without re-fetching or re-scanning the full corpus.

  techtwitter-pp-cli since 24h --agent
  

• momentum — Show which topics are rising, falling, or newly appearing across the heatmap snapshots stored on each sync.

  Use this when the question is about change over time, which no single API call can answer.

  techtwitter-pp-cli momentum --window 7d --json
  

• narrative — Surface keywords that newly emerged or accelerated versus prior snapshots, grounded in supporting stored tweets.

  Pick this over a one-shot narrative pull when you want what is newly emerging, not just what is currently large.

  techtwitter-pp-cli narrative --json
  

• author-rank — Rank authors by accumulated stored engagement over a window, each with their best curated tweet.

  Use this for a leaderboard that compounds as you sync, not the API's one-shot day winner.

  techtwitter-pp-cli author-rank --window 7d --limit 10 --json
  

• time-travel — Show the curated tweets for a specific date (YYYY-MM-DD, today, yesterday, or latest), live or fully offline from the local store.

  Use this to pull the snapshot of what tech Twitter was saying on a given day, with no live call once synced.

  techtwitter-pp-cli time-travel 2026-06-07 --limit 10 --json
  

Agent-native evidence, offline

• digest — Assemble a read-list from the local store for a window: top tweets, recent articles, and top authors.

  Reach for this to hand an agent a cited, single-shot "what's happening in tech" rollup with zero extra calls.

  techtwitter-pp-cli digest --window 24h --agent
  

• evidence — Build an evidence bundle mirroring the agent-context kinds from local SQLite, with canonical-URL citations and no network.

  Use this when an agent needs cited evidence but you want it grounded in the local mirror with no upstream call.

  techtwitter-pp-cli evidence read-list --agent --select evidence.title,evidence.canonicalUrl
  

Recipes

Cited what-changed evidence for an agent

techtwitter-pp-cli agent --kind what-changed --agent --select evidence.title,evidence.canonicalUrl,evidence.qualityScore

Pulls a cited evidence bundle and narrows the deeply nested response to just title, citation URL, and quality score so an agent isn't flooded with media and metric fields.

Daily tech standup, offline

techtwitter-pp-cli digest --window 24h --agent

Composes a read-list of top tweets, recent articles, and top authors for the last day from the local mirror, agent-formatted with citations.

What is newly emerging

techtwitter-pp-cli narrative --json

Diffs stored heatmap snapshots to surface keywords that just emerged or accelerated, each grounded in supporting stored tweets.

Search the curated corpus offline

techtwitter-pp-cli search "agentic coding" --json --limit 10

Full-text searches the synced local store with no network call, returning quality-scored curated tweets as JSON.

Track a topic's momentum

techtwitter-pp-cli momentum --window 7d --json

Shows which topics are rising, falling, or newly appearing across the snapshots stored over the last week of syncs.

Usage

Run techtwitter-pp-cli --help for the full command reference and flag list.

Commands

agent

Machine-agent evidence bundles

• techtwitter-pp-cli agent - Cited evidence bundle for an agent question

articles

Long-form articles backed by tweet provenance

• techtwitter-pp-cli articles - List long-form articles

command

Command-center signals (hot takes, main character, heatmap, stats, by-date)

• techtwitter-pp-cli command heatmap - Topic momentum heatmap (keyword, count, engagement)
• techtwitter-pp-cli command hot-takes - High-reply, debate-heavy curated tweets
• techtwitter-pp-cli command main-character - The day's most-engaged authors (main character)
• techtwitter-pp-cli command stats - Corpus index health stats
• techtwitter-pp-cli command tweets-by-date - Curated tweets for a date (today, yesterday, latest, or YYYY-MM-DD)

newsletters

In-app newsletters (Threads)

• techtwitter-pp-cli newsletters - List published in-app newsletters

profiles

Curated author profiles

• techtwitter-pp-cli profiles - Search author profiles by name, handle, or bio

tweets

Search and browse the curated tweet stream

• techtwitter-pp-cli tweets author - Curated tweets for a specific author handle
• techtwitter-pp-cli tweets get - Get a single curated tweet by UUID (with prev/next neighbors)
• techtwitter-pp-cli tweets latest - Get the single most recent curated tweet (with nextTweetId)
• techtwitter-pp-cli tweets monthly - Curated tweets for a given month
• techtwitter-pp-cli tweets search - Search curated tweets by text (relevance-ranked)
• techtwitter-pp-cli tweets topic - Curated tweets for a topic slug
• techtwitter-pp-cli tweets trending - Ranked trending curated tweets from the last 7 days

Output Formats

# Human-readable table (default in terminal, JSON when piped)
techtwitter-pp-cli articles

# JSON for scripting and agents
techtwitter-pp-cli articles --json

# Filter to specific fields
techtwitter-pp-cli articles --json --select id,name,status

# Dry run — show the request without sending
techtwitter-pp-cli articles --dry-run

# Agent mode — JSON + compact + no prompts in one flag
techtwitter-pp-cli articles --agent

Agent Usage

This CLI is designed for AI agent consumption:

• Non-interactive - never prompts, every input is a flag
• Pipeable - --json output to stdout, errors to stderr
• Filterable - --select id,name returns only fields you need
• Previewable - --dry-run shows the request without sending
• Read-only by default - this CLI does not create, update, delete, publish, send, or mutate remote resources
• Offline-friendly - sync/search commands can use the local SQLite store when available
• Agent-safe by default - no colors or formatting unless --human-friendly is set

Exit codes: 0 success, 2 usage error, 3 not found, 5 API error, 7 rate limited, 10 config error.

Health Check

techtwitter-pp-cli doctor

Verifies configuration and connectivity to the API.

Configuration

Config file: ~/.config/techtwitter-pp-cli/config.toml

Static request headers can be configured under headers; per-command header overrides take precedence.

Troubleshooting

Not found errors (exit code 3)

• Check the resource ID is correct
• Run the list command to see available items

API-specific

• 403 Forbidden from the API — The CLI must send a browser-shaped User-Agent; bare scraper UAs are blocked on all non-machine paths. The default client already does this — only override --user-agent with a browser string.
• A command redirects or returns the homepage — That endpoint is auth-gated and out of scope for the public CLI. Use the documented public commands (search, trending, latest, author, topic, articles, products, agent context).
• Offline commands return nothing — Run techtwitter-pp-cli sync first to populate the local mirror; since/momentum/digest read from stored data.

Sources & Inspiration

This CLI was built by studying these projects and resources:

• sferik/x-cli — Ruby
• public-clis/twitter-cli — JavaScript
• hay/twitter-cli — JavaScript
• Infatoshi/x-cli — Python

Generated by CLI Printing Press