Pp X Twitter

<!-- GENERATED FILE — DO NOT EDIT.
     This file is a verbatim mirror of library/social-and-messaging/x-twitter/SKILL.md,
     regenerated post-merge by tools/generate-skills/. Hand-edits here are
     silently overwritten on the next regen. Edit the library/ source instead.
     See the repository agent guide, section "Generated artifacts: registry.json, cli-skills/". -->

X (Twitter) — Printing Press CLI

Prerequisites: Install the CLI

This skill drives the x-twitter-pp-cli binary. You must verify the CLI is installed before invoking any command from this skill. If it is missing, install it first:

1. Install via the Printing Press installer. It defaults binaries to $HOME/.local/bin on macOS/Linux and %LOCALAPPDATA%\Programs\PrintingPress\bin on Windows:

   npx -y @mvanhorn/printing-press-library install x-twitter --cli-only

2. Verify: x-twitter-pp-cli --version
3. Ensure the reported install directory is on $PATH for the agent/runtime that will invoke this skill.

If the npx install fails (no Node, offline, etc.), fall back to a direct Go install (requires Go 1.26.6 or newer). This installs into $GOPATH/bin (default $HOME/go/bin), so add that directory to $PATH instead:

go install github.com/mvanhorn/printing-press-library/library/social-and-messaging/x-twitter/cmd/x-twitter-pp-cli@latest

If --version reports "command not found" after install, the runtime cannot see the binary directory on $PATH. Do not proceed with skill commands until verification succeeds.

Mirrors the official X v2 API and adds what no other X tool has: a local SQLite store you can sync once and query many times with FTS5 search and group-by analytics, agent-native --json/--select output, and an MCP server that exposes the whole surface to AI agents through token-efficient orchestration plus named multi-step intents. Start pasted-link workflows with post resolve, use thread context when a post needs parent/quote/reply context, save durable source material with collection save/list/export, track ongoing searches with monitor create/run/list, package saved activity with brief, snapshot accounts with account snapshot, find launch or repo links with url mentions, track post metrics with performance snapshot/backfill/analyze, export account/query timelines with timeline export, reconstruct synced conversation threads offline with thread show, compose self-reply threads from markdown with thread compose, author long-form X Articles from markdown with articles-publish-md, and rescue your bookmark graveyard with users bookmarks find — keyword and author search over your synced bookmarks, which X itself gives you no way to search.

When to Use This CLI

For a ranked readout of recent posts, run x-twitter-pp-cli top-posts --metric engagement --limit 10 --max-fetch 100 --json. It reads the live X timeline, so each page may use paid API credits. --max-fetch accepts 1 to 1000 posts, with a small extra-page budget for sparse responses. A leaderboard returned at that budget is partial and has truncated: true in every JSON row. --user-id selects a numeric account ID without a separate username lookup; without it, the command uses the authenticated user. JSON rows name the effective score_metric, and missing impression scores are null rather than zero. --dry-run makes no request.

Reach for this CLI when a task involves reading, searching, or archiving X (Twitter) data and you want the results queryable offline rather than re-fetched each time — building a searchable corpus of posts, reconstructing a conversation thread, snapshotting a user's recent posts with engagement, or monitoring mentions incrementally. It is also the right choice when an AI agent needs an X surface with read-only/destructive safety hints and named multi-step intents rather than a pile of raw endpoint calls. Prefer it over raw API calls whenever the same data will be queried more than once, since the local store avoids re-spending per-read credits.

Unique Capabilities

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

Local state that compounds

• post resolve — Normalize any X post URL or raw post ID into a canonical structured record. It prefers local data in auto mode, falls back to public v2 reads when needed, includes provenance (live, local, or mixed), and emits suggested next workflow commands.

  Use this as the first command when an agent starts from a pasted X link. It avoids brittle URL parsing and returns stable fields for downstream workflows.

  x-twitter-pp-cli post resolve https://x.com/user/status/123 --agent
  x-twitter-pp-cli post resolve 123 --include author,media,links,refs,metrics --agent

• thread context — Resolve a post URL or ID, include parent and quoted posts when available, and optionally include bounded replies from the local store and/or recent search.

  Use this before summarizing or drafting around a post. thread show is still the pure offline conversation reconstruction command; thread context is the URL-first workflow that can mix local and live data.

  x-twitter-pp-cli thread context https://x.com/user/status/123 --agent
  x-twitter-pp-cli thread context 123 --replies --depth 3 --limit 100 --agent

• collection save/list/export — Save resolved X posts into durable named local collections, then list or export them as markdown, JSON, JSONL, or CSV. This never writes to X; it only writes the local SQLite store.

  Use collections for research libraries, launch mentions, examples, recruiting/source material, and anything an agent should reuse offline after the first API read.

  x-twitter-pp-cli collection save https://x.com/user/status/123 --collection ai-agents --note "Good framing" --agent
  x-twitter-pp-cli collection list ai-agents --agent
  x-twitter-pp-cli collection export ai-agents --format markdown

• monitor create/run/list — Create named query, URL, or account monitors, then run them repeatedly with local watermarks and dedupe. monitor create and monitor run write only local SQLite state; they never post, like, reply, follow, or mutate X.

  Use monitors for launch mentions, product/customer feedback, account tracking, and recurring agent jobs. --since last uses the saved watermark; --preview fetches without updating local state.

  x-twitter-pp-cli monitor create ai-labs --query 'from:openai OR from:anthropic' --agent
  x-twitter-pp-cli monitor create product-mentions --url https://example.com --agent
  x-twitter-pp-cli monitor run ai-labs --since last --agent
  x-twitter-pp-cli monitor list --agent

• brief — Build a deterministic source-backed JSON or markdown brief from monitor results, collections, or explicit post IDs. It packages links, authors, text, and available metrics; it does not invent conclusions or run LLM summarization.

  Use this when an agent needs a daily/weekly X activity packet or a collection summary that can be pasted into notes, docs, or a CRM.

  x-twitter-pp-cli brief --monitor ai-labs --since 24h --agent
  x-twitter-pp-cli brief --collection launch-feedback --format markdown

• account snapshot — Capture profile basics, public metrics, pinned post, and recent posts for a username or user ID. It is read-only toward X and uses local data first unless --live or --data-source live is set.

  x-twitter-pp-cli account snapshot @username --recent 20 --agent
  x-twitter-pp-cli account snapshot 12345 --include recent,profile,metrics,pinned --format markdown

• url mentions — Search for recent posts mentioning a URL, domain, repo, article, or product page. It can optionally save results into a local collection or create/update a local monitor for future runs.

  x-twitter-pp-cli url mentions https://example.com --since 7d --agent
  x-twitter-pp-cli url mentions github.com/org/repo --collection launch-feedback --monitor repo-links --agent

• performance snapshot/backfill/analyze — Store timestamped post metrics locally, backfill recent account posts when auth allows, and analyze saved snapshots by type, hour, media, link presence, or label. Missing metrics stay nullable/absent; the CLI does not treat unavailable fields as zero. Snapshot output includes public_metrics, available non-public/organic metrics, metric_source, and metric_availability.

  x-twitter-pp-cli performance snapshot --ids 123,456 --label 24h --agent
  x-twitter-pp-cli performance backfill --mine --days 90 --agent
  x-twitter-pp-cli performance analyze --since 90d --group-by type,hour,has_media,has_link --agent

• timeline export — Export an account or query timeline as markdown, JSON, or JSONL. Account exports use local synced tweets when available and fetch live only when needed or requested.

  x-twitter-pp-cli timeline export @username --since 30d --format markdown
  x-twitter-pp-cli timeline export --query 'ai agents' --since 7d --format jsonl

• thread show — Rebuild a full conversation thread from your locally synced posts — ordered and depth-tagged — without re-spending API read credits.

  When an agent needs the shape of a discussion (who replied to whom, in order), reach for this instead of paginating the search API and re-assembling the tree by hand.

  x-twitter-pp-cli thread show 1750000000000000000 --agent

• users bookmarks find — Search your synced bookmarks by keyword and/or author, offline. X has no bookmark search and its API exposes no bookmark timestamp, so bookmarks pile up unread; this rebuilds the missing retrieval layer from the local store. Read-only and free to re-run once synced — the X read credit is spent once at sync time, not per query.

  The "I bookmarked something about this and can't find it" rescue. Sync bookmarks once, then let an agent retrieve and act on them (summarize, draft a thread, cluster) — the offline store is the agent's working set, not a per-query API spend.

  # one-time populate (personal read — needs X_OAUTH2_USER_TOKEN); add author field + users for --from
  x-twitter-pp-cli sync --resources bookmarks --param tweet.fields=author_id,created_at
  x-twitter-pp-cli sync --resources users
  
  x-twitter-pp-cli users bookmarks find "rust async" --agent
  x-twitter-pp-cli users bookmarks find "llm" --from @karpathy --limit 20 --agent

Authoring workflows

• thread compose — Split a markdown file into a numbered, 280-char-packed self-reply thread; prints by default and only posts with --post.

  Compose a thread from a document deterministically; the dry-run default lets an agent preview the exact tweets before any write.

  x-twitter-pp-cli thread compose ./update.md

• articles-publish-md — Parse a markdown file with YAML frontmatter into the Draft.js content_state JSON X's Articles editor accepts; previews by default; --draft creates a new draft, --update edits an existing draft, --post publishes publicly.

  The only programmatic way to author a long-form X Article from a document; preview, --draft, and --update keep it private until you explicitly --post.

  The converter supports paragraphs, #/## headers (### and deeper are downgraded to ##), lists, blockquotes, fenced code blocks, tables, dividers, image lines (![alt](path)), standalone tweet URLs (native embeds), bold/italic/code inline styles (including inside blockquotes), and [text](url) inline links, which become real LINK entities (working hyperlinks) in the article. Lines that are HTML comments (<!-- ... -->) are stripped and never ship as article text.

  x-twitter-pp-cli articles-publish-md ./post.md
  x-twitter-pp-cli articles-publish-md ./post.md --update 1750000000000000000

• articles update-md — Update an existing X Article draft in place from a markdown file: title (frontmatter), body, links, and new inline images, all in one command. Find the article id via articles list --agent.

  Edit the markdown, re-run one command. No duplicate drafts: the draft keeps its id, so the edit URL and any saved state stay valid.

  x-twitter-pp-cli articles update-md ./post.md --article-id 1750000000000000000 --agent

  WARNING — body replacement: articles update-md replaces the ENTIRE body of the target draft. Anything added by hand in the X composer that the markdown converter cannot reproduce is destroyed by the update. The command preflights the draft's content_state and refuses when it finds entity types outside the converter's emit set (LINK, MARKDOWN, MEDIA, TWEET, DIVIDER); pass --replace-unknown-entities only when you genuinely want to overwrite those artifacts. Markdown-authored content round-trips cleanly; if a draft holds composer-only embeds or other manual artifacts, edit it in the composer instead.

  Draft-only by default: a published article is refused unless you pass --republish, which runs Unpublish -> UpdateContent -> Publish (the article is briefly unpublished). Use --dry-run to preview the converted payload with no API call.

Command Reference

account-activity — Endpoints relating to retrieving, managing AAA subscriptions

• x-twitter-pp-cli account-activity create-subscription — Creates an Account Activity subscription for the user and the given webhook.
• x-twitter-pp-cli account-activity delete-subscription — Deletes an Account Activity subscription for the given webhook and user ID.
• x-twitter-pp-cli account-activity get-subscription-count — Retrieves a count of currently active Account Activity subscriptions.
• x-twitter-pp-cli account-activity get-subscriptions — Retrieves a list of all active subscriptions for a given webhook.
• x-twitter-pp-cli account-activity validate-subscription — Checks a user’s Account Activity subscription for a given webhook.

activity — Manage activity

• x-twitter-pp-cli activity create-subscription — Creates a subscription for an X activity event
• x-twitter-pp-cli activity delete-subscription — Deletes a subscription for an X activity event
• x-twitter-pp-cli activity delete-subscriptions-by-ids — Deletes multiple subscriptions for X activity events by their IDs
• x-twitter-pp-cli activity get-subscriptions — Get a list of active subscriptions for XAA
• x-twitter-pp-cli activity update-subscription — Updates a subscription for an X activity event

chat — Manage chat

• x-twitter-pp-cli chat add-group-members — Adds one or more members to an existing encrypted Chat group conversation, rotating the conversation key.
• x-twitter-pp-cli chat create-conversation — Creates a new encrypted Chat group conversation on behalf of the authenticated user.
• x-twitter-pp-cli chat get-conversation — Returns metadata for a Chat conversation including type, muted status, and group details. Use chat_conversation.
• x-twitter-pp-cli chat get-conversation-events — Retrieves messages and key change events for a specific Chat conversation with pagination support.
• x-twitter-pp-cli chat get-conversations — Retrieves a list of Chat conversations for the authenticated user's inbox.
• x-twitter-pp-cli chat initialize-conversation-keys — Initializes encryption keys for a Chat conversation.
• x-twitter-pp-cli chat initialize-group — Initializes a new XChat group conversation and returns a unique conversation ID.
• x-twitter-pp-cli chat mark-conversation-read — Marks a specific Chat conversation as read on behalf of the authenticated user.
• x-twitter-pp-cli chat media-download — Downloads encrypted media bytes from an XChat conversation. The response body contains raw binary bytes.
• x-twitter-pp-cli chat media-upload-append — Appends media data to an XChat upload session.
• x-twitter-pp-cli chat media-upload-finalize — Finalizes an XChat media upload session.
• x-twitter-pp-cli chat media-upload-initialize — Initializes an XChat media upload session.
• x-twitter-pp-cli chat send-message — Sends an encrypted message to a specific Chat conversation.
• x-twitter-pp-cli chat send-typing-indicator — Sends a typing indicator to a specific Chat conversation on behalf of the authenticated user.

communities — Manage communities

• x-twitter-pp-cli communities get-by-id — Retrieves details of a specific Community by its ID.
• x-twitter-pp-cli communities search — Retrieves a list of Communities matching the specified search query.

compliance — Endpoints related to keeping X data in your systems compliant

• x-twitter-pp-cli compliance create-jobs — Creates a new Compliance Job for the specified job type.
• x-twitter-pp-cli compliance get-jobs — Retrieves a list of Compliance Jobs filtered by job type and optional status.
• x-twitter-pp-cli compliance get-jobs-by-id — Retrieves details of a specific Compliance Job by its ID.

connections — Endpoints related to streaming connections

• x-twitter-pp-cli connections delete-all — Terminates all active streaming connections for the authenticated application.
• x-twitter-pp-cli connections delete-by-endpoint — Terminates all streaming connections for a specific endpoint ID for the authenticated application.
• x-twitter-pp-cli connections delete-by-uuids — Terminates multiple streaming connections by their UUIDs for the authenticated application.
• x-twitter-pp-cli connections get-history — Returns active and historical streaming connections with disconnect reasons for the authenticated application.

dm-conversations — Manage dm conversations

• x-twitter-pp-cli dm-conversations create-direct-messages-by-participant-id — Sends a new direct message to a specific participant by their ID.
• x-twitter-pp-cli dm-conversations create-direct-messages-conversation — Initiates a new direct message conversation with specified participants.
• x-twitter-pp-cli dm-conversations get-direct-messages-events-by-participant-id — Retrieves direct message events for a specific conversation.
• x-twitter-pp-cli dm-conversations media-download — Downloads media attached to a legacy Direct Message.

dm-events — Manage dm events

• x-twitter-pp-cli dm-events delete-direct-messages-events — Deletes a specific direct message event by its ID, if owned by the authenticated user.
• x-twitter-pp-cli dm-events get-direct-messages-events — Retrieves a list of recent direct message events across all conversations.
• x-twitter-pp-cli dm-events get-direct-messages-events-by-id — Retrieves details of a specific direct message event by its ID.

evaluate-note — Manage evaluate note

• x-twitter-pp-cli evaluate-note — Endpoint to evaluate a community note.

insights — Manage insights

• x-twitter-pp-cli insights get-historical — Retrieves historical engagement metrics for specified Posts within a defined time range.
• x-twitter-pp-cli insights get-insights28-hr — Retrieves engagement metrics for specified Posts over the last 28 hours.

lists — Endpoints related to retrieving, managing Lists

• x-twitter-pp-cli lists create — Creates a new List for the authenticated user.
• x-twitter-pp-cli lists delete — Deletes a specific List owned by the authenticated user by its ID.
• x-twitter-pp-cli lists get-by-id — Retrieves details of a specific List by its ID.
• x-twitter-pp-cli lists update — Updates the details of a specific List owned by the authenticated user by its ID.

media — Endpoints related to Media

• x-twitter-pp-cli media append-upload — Appends data to a Media upload request.
• x-twitter-pp-cli media create-metadata — Creates metadata for a Media file.
• x-twitter-pp-cli media create-subtitles — Creates subtitles for a specific Media file.
• x-twitter-pp-cli media delete-subtitles — Deletes subtitles for a specific Media file.
• x-twitter-pp-cli media finalize-upload — Finalizes a Media upload request.
• x-twitter-pp-cli media get-analytics — Retrieves analytics data for media.
• x-twitter-pp-cli media get-by-key — Retrieves details of a specific Media file by its media key.
• x-twitter-pp-cli media get-by-keys — Retrieves details of Media files by their media keys.
• x-twitter-pp-cli media get-upload-status — Retrieves the status of a Media upload by its ID.
• x-twitter-pp-cli media initialize-upload — Initializes a media upload.
• x-twitter-pp-cli media upload — Uploads a media file for use in posts or other content.

news — Endpoint for retrieving news stories

• x-twitter-pp-cli news get — Retrieves news story by its ID.
• x-twitter-pp-cli news search — Retrieves a list of News stories matching the specified search query.

notes — Manage notes

• x-twitter-pp-cli notes create-community — Creates a community note endpoint for LLM use case.
• x-twitter-pp-cli notes delete-community — Deletes a community note.
• x-twitter-pp-cli notes search-community-written — Returns all the community notes written by the user.
• x-twitter-pp-cli notes search-eligible-posts — Returns all the posts that are eligible for community notes.

openapi-json — Manage openapi json

• x-twitter-pp-cli openapi-json — Retrieves the full OpenAPI Specification in JSON format. (See https://github.

spaces — Endpoints related to retrieving, managing Spaces

• x-twitter-pp-cli spaces get-by-creator-ids — Retrieves details of Spaces created by specified User IDs.
• x-twitter-pp-cli spaces get-by-id — Retrieves details of a specific space by its ID.
• x-twitter-pp-cli spaces get-by-ids — Retrieves details of multiple Spaces by their IDs.
• x-twitter-pp-cli spaces search — Retrieves a list of Spaces matching the specified search query.

trends — Manage trends

• x-twitter-pp-cli trends <woeid> — Retrieves trending topics for a specific location identified by its WOEID.

tweets — Endpoints related to retrieving, searching, and modifying Tweets

• x-twitter-pp-cli tweets create-posts — Creates a new Post for the authenticated user, or edits an existing Post when edit_options are provided.
• x-twitter-pp-cli tweets create-webhooks-stream-link — Creates a link to deliver FilteredStream events to the given webhook.
• x-twitter-pp-cli tweets delete-posts — Deletes a specific Post by its ID, if owned by the authenticated user.
• x-twitter-pp-cli tweets delete-webhooks-stream-link — Deletes a link from FilteredStream events to the given webhook.
• x-twitter-pp-cli tweets get-posts-analytics — Retrieves analytics data for specified Posts within a defined time range.
• x-twitter-pp-cli tweets get-posts-by-id — Retrieves details of a specific Post by its ID.
• x-twitter-pp-cli tweets get-posts-by-ids — Retrieves details of multiple Posts by their IDs.
• x-twitter-pp-cli tweets get-posts-counts-all — Retrieves the count of Posts matching a search query from the full archive.
• x-twitter-pp-cli tweets get-posts-counts-recent — Retrieves the count of Posts from the last 7 days matching a search query.
• x-twitter-pp-cli tweets get-rule-counts — Retrieves the count of rules in the active rule set for the filtered stream.
• x-twitter-pp-cli tweets get-rules — Retrieves the active rule set or a subset of rules for the filtered stream.
• x-twitter-pp-cli tweets get-webhooks-stream-links — Get a list of webhook links associated with a filtered stream ruleset.
• x-twitter-pp-cli tweets search-posts-all — Retrieves Posts from the full archive matching a search query.
• x-twitter-pp-cli tweets search-posts-recent — Retrieves Posts from the last 7 days matching a search query.
• x-twitter-pp-cli tweets update-rules — Adds or deletes rules from the active rule set for the filtered stream.

usage — Manage usage

• x-twitter-pp-cli usage — Retrieves usage statistics for Posts over a specified number of days.

users — Endpoints related to retrieving, managing relationships of Users

• x-twitter-pp-cli users get-by-id — Retrieves details of a specific User by their ID.
• x-twitter-pp-cli users get-by-ids — Retrieves details of multiple Users by their IDs.
• x-twitter-pp-cli users get-by-username — Retrieves details of a specific User by their username.
• x-twitter-pp-cli users get-by-usernames — Retrieves details of multiple Users by their usernames.
• x-twitter-pp-cli users get-me — Retrieves details of the authenticated user.
• x-twitter-pp-cli users get-public-keys — Returns the public keys and Juicebox configuration for the specified users.
• x-twitter-pp-cli users get-reposts-of-me — Retrieves a list of Posts that repost content from the authenticated user.
• x-twitter-pp-cli users get-trends-personalized-trends — Retrieves personalized trending topics for the authenticated user.
• x-twitter-pp-cli users bookmarks find [query] — Searches locally synced bookmarks by keyword and/or author without another API read.
• x-twitter-pp-cli users likes post <user_id> --tweet-id <tweet_id> — Likes a post on behalf of the authenticated user.
• x-twitter-pp-cli users likes unlike-post <user_id> <tweet_id> — Unlikes a post on behalf of the authenticated user.
• x-twitter-pp-cli users search — Retrieves a list of Users matching a search query.

webhooks — Manage webhooks

• x-twitter-pp-cli webhooks create — Creates a new webhook configuration.
• x-twitter-pp-cli webhooks create-replay-job — Creates a replay job to retrieve events from up to the past 24 hours for all events delivered or attempted to be
• x-twitter-pp-cli webhooks delete — Deletes an existing webhook configuration.
• x-twitter-pp-cli webhooks get — Get a list of webhook configs associated with a client app.
• x-twitter-pp-cli webhooks validate — Triggers a CRC check for a given webhook.