Sweetistics CLI

Twitter/X archive analysis, timeline insights, and AI chat automation straight from your terminal.

Install

• Stable release (bundled runtime):

  npm install -g sweetistics
  # or
  pnpm add -g sweetistics

• One-off execution without installing:

  pnpm dlx sweetistics@latest --help
  npx sweetistics@latest timeline list --json

Quick Start

# Launch the interactive import & setup wizard
sweetistics

# Authenticate or inspect your stored credentials
sweetistics login
sweetistics whoami

# Import a downloaded Twitter archive ZIP
sweetistics import ~/Downloads/twitter-archive.zip

# Review cached timeline summaries or export tweets
sweetistics timeline summary --limit 1 --json
sweetistics timeline fetch --limit 200 --format csv

# Chat against your archive or live data
sweetistics chat send --archive "Surface my 2024 highlights"

Global Flags

| Flag | Description | | --- | --- | | --env <prod|dev|local> | Switch between hosted Sweetistics and http://localhost:3000. | | --api-base <url> | Override the API origin (takes precedence over --env). | | --verbose | Emit diagnostic logs for debugging and QA. |

Most commands also accept --timeout <ms> and --json for automation pipelines.

Command Map

| Area | Command | Highlights | | --- | --- | --- | | Auth | login, logout, whoami | Device auth with secure key storage. | | Archives | analyze, import, validate | Inspect, stage, and upload Twitter archive ZIPs with batching + retries. | | Timelines | timeline list|fetch|run|summary|snapshot | Stream fresh analyses, export cached tweets (CSV/JSON/Markdown), or force-refresh snapshots. | | Pulse | pulse list|refresh|settings | Track follow/unfollow deltas and delivery preferences. | | Insights | insights show | Summaries of top authors and engagement patterns. | | Arena | arena analyze|get|list|delete | Run multi-profile comparisons with AI scoring. | | User | user run|list | Generate long-form user analyses with realtime streaming support. | | Chat | chat, chat send, chat models | Conversational tooling for archives or live data (supports JSON output and tracing). |

Publishing Checklist

The npm package bundles every internal @sweetistics/* module into dist/vendor/**, so no extra installs are required. Before publishing:

1. pnpm run build:packages
2. pnpm --filter ./packages/cli run build
3. pnpm --filter ./packages/cli exec npm pack
4. Smoke test the tarball from a clean directory:

   TMPDIR=$(mktemp -d)
   cp packages/cli/sweetistics-*.tgz "$TMPDIR"/
   (cd "$TMPDIR" && npm init -y >/dev/null \
     && npm install ./sweetistics-*.tgz \
     && npx sweetistics --help)

Need the full surface area? See docs/cli.md in the Sweetistics repo for exhaustive command reference and advanced workflows.