threads-cli

threads-cli is a terminal-first CLI for personal Threads workflows.

It separates unofficial read workflows from official publishing workflows:

• Reads use your own authenticated Threads/Instagram web session and unofficial Instagram private endpoints.
• Canonical post commands use the official Threads API with OAuth access tokens.
• The CLI emits sns-json-v1 JSON for AI agents and Skim.

Status

This repository is an early golden-template clone of linkedin-cli.

Implemented and covered by focused tests:

• threads-cli auth-status
• threads-cli auth status --json
• threads-cli auth cookie-file --from-stdin
• threads-cli read feed --limit 5 --json
• threads-cli read feed --user-id 12345 --limit 5 --json
• threads-cli read thread https://www.threads.net/@aiden/post/ABC123 --json
• threads-cli post text --text "..." --dry-run --json
• threads-cli post text --text "..." --json
• threads-cli post media --text "..." --media-url "https://..." --json
• sns-json-v1 success/error envelopes

Live publishing requires a valid Threads API token and should only be run after dry-run review.

Important Notes

• This project is not affiliated with Meta, Instagram, or Threads.
• Read commands are unofficial and rely on private endpoint behavior. Review the terms that apply to your account.
• Canonical post commands are designed around official Threads publishing APIs.
• Session cookies and OAuth tokens are credentials. Treat them like passwords.
• Do not use this project for spam, bulk scraping, engagement loops, or anything that violates platform rules.

Installation

uv sync

Read Auth

Read commands resolve cookies from:

1. THREADS_COOKIE_HEADER
2. THREADS_COOKIE_FILE or ~/.config/threads/cookies.env
3. THREADS_READ_SESSION_FILE
4. ~/.config/threads/read-session.json

The cookie file stores a shell-quoted THREADS_COOKIE_HEADER line with 0600 permissions. Create it without saving the raw cookie header in shell history:

uv run threads-cli auth cookie-file --from-stdin

Paste the one-line Threads/Instagram Cookie header, press Return, then press Control+D.

The read-session file uses Playwright storage_state JSON shape.

Verify read auth before extraction:

uv run threads-cli auth status --json
uv run threads-cli auth-status

auth status --json reports cookie presence in sns-json-v1. auth-status also runs a live timeline probe. Neither command prints raw cookie values.

Official Post Auth

Post commands resolve OAuth credentials from:

1. THREADS_ACCESS_TOKEN + THREADS_USER_ID
2. THREADS_OAUTH_FILE
3. ~/.config/threads/oauth.json

Token file shape:

{
  "access_token": "...",
  "user_id": "12345",
  "graph_version": "v1.0"
}

Commands

uv run threads-cli auth-status
uv run threads-cli auth status --json
uv run threads-cli auth cookie-file --from-stdin
uv run threads-cli read feed --limit 10 --json
uv run threads-cli read feed --limit 10 --user-id 12345 --json
uv run threads-cli read thread https://www.threads.net/@aiden/post/ABC123 --json
uv run threads-cli read thread 987654321 --json
uv run threads-cli post text --text "hello from threads-cli" --dry-run --json
uv run threads-cli post text --text "hello from threads-cli" --json
uv run threads-cli post media --text "hello with image" --media-url "https://example.com/image.jpg" --json

read thread accepts a Threads post URL or numeric media id. URL extraction reads the Threads web page and looks for embedded post JSON. Numeric id extraction uses the private Instagram media info endpoint.

Development

uv run pytest -q
uv run ruff check .
uv run python -m compileall threads_cli tests