threads-cli

A clean CLI for the official Meta Threads API (graph.threads.net).

Note: The official Threads API does not provide Home / For You / Following feed access.

Install

pipx install git+https://github.com/finolabs/threads-cli
threads --help

Full walkthrough — CLI + skill, every runtime, with verify/uninstall steps: docs/INSTALL.md.

(Dev/editable):

python3 -m venv .venv
source .venv/bin/activate
pip install -e '.[dev]'
threads --help

Setup (once)

threads setup    # prompts for a draft folder + your Meta app credentials,
                 # then offers to run OAuth login right away
threads me       # verify

setup is interactive: it prints how to create a Meta app, asks for your THREADS_APP_ID/THREADS_APP_SECRET (written to ~/.threads/.env, 0600), and offers to log in — no hand-editing. To script it, pass --content-dir, --app-id, --app-secret (and --no-login); then run threads login separately.

Need a Meta app first? You must create one to get THREADS_APP_ID / THREADS_APP_SECRET (the Threads API has no personal tokens). Step-by-step: Meta app setup guide.

setup also lets you pick the OAuth callback port (default 8473, saved in ~/.threads/config.json). View or change settings anytime without re-running setup:

threads config                    # show content dir, callback port, paths, status
threads config set port 9000      # change the callback port (update your Meta redirect URI too)
threads config set content-dir ~/td

Credentials default to ~/.threads/.env, so most commands need no --env-file. Pass --env-file <path> to override.

Export your data (for analysis)

Pull all your posts/replies/mentions (auto-paginated) into a JSON or CSV file:

threads export --type posts --out posts.json
threads export --type posts --with-insights --out posts.csv
threads export --type replies --out replies.json
threads export --type mentions --out mentions.json

--user-id defaults to THREADS_USER_ID (else me). Format is inferred from the --out extension. Use --max, --page-size, and --sleep to bound or throttle.

For a single file with everything (profile + posts + insights + replies + mentions + follower series + quota), use threads snapshot --out snapshot.json.

Publish (draft → approve → publish)

Publishing is draft-first: content is saved as a Markdown file for review, and a post only goes out after explicit approval.

threads draft create --text "Hello Threads"   # saved as a Markdown draft
threads draft list                             # review
threads draft approve <id>                     # approve the exact text
threads draft publish <id> --confirm           # publish (omit --confirm for a dry run)

For AI agents

The skill ships through three channels — pick the one that matches your runtime.

1. Claude Code plugin marketplace (cleanest for Claude Code):

/plugin marketplace add finolabs/threads-cli
/plugin install threads@finolabs

2. Any CLI agent (Claude Code, Codex, etc.) — drop the skill into its skill dir:

threads skills install                 # auto-detects your agent CLIs; prompts if several
threads skills install --target claude # a specific agent (claude, codex, ...)
threads skills install --target all    # every detected agent
threads skills list                    # see detected agents and what's installed

You name the agent — the skill directory is auto-detected. --target also accepts a directory path if you need one.

3. Claude Desktop / Cowork — installs skills by uploading a zip, not from a directory. Build one and upload it under Customize → Skills:

threads skills bundle           # writes ./threads-skill.zip

Channels 1 and 3 distribute only the skill (the playbook). The threads CLI it drives still needs pipx install git+https://github.com/finolabs/threads-cli — the skill's onboarding covers that.

See AGENTS.md for the agent workflow.

License

MIT — see LICENSE.