Sweetistics CLI

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

Install

- Stable release (bundled runtime):
``bash
npm install -g sweetistics
# or
pnpm add -g sweetistics
`
- One-off execution without installing:
`bash
pnpm dlx sweetistics@latest --help
npx sweetistics@latest timeline list --json
`

Quick Start

`bash


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 | Switch between hosted Sweetistics and http://localhost:3000. |
| --api-base | Override the API origin (takes precedence over --env). |
| --verbose | Emit diagnostic logs for debugging and QA. |

Most commands also accept --timeout 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:
`bash
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.