threads-cli

Playwright-based Threads CLI for posting, reading, browsing, and debugging Threads web interactions.

threads-cli is built as a small command-oriented tool:

• authenticate with an existing persistent browser profile
• create posts with images
• create replies
• browse your profile or home feed interactively
• inspect posts and replies with structured debug output

Install

Requirements:

• Python 3.10+
• Playwright
• Chromium browser installed for Playwright

Install in editable mode from this package directory:

cd /home/jinnyeong/openclaw/threads-cli
pip install -e .
playwright install chromium

Core Behavior

• Default execution is headless.
• If a command requires login and the current session is not authenticated, threads-cli switches to headed mode for login and then resumes.
• Session data is stored per profile under:

~/.threads_automation_profiles/<profile>/

• Debug artifacts are stored under:

~/.threads_automation_profiles/<profile>/debug/

Global Options

Common flags:

threads-cli --profile default --headless
threads-cli --headed
threads-cli --json
threads-cli --debug
threads-cli --log-lang en
threads-cli --bypass-cooldown
threads-cli --timeout-ms 15000

Notes:

• --json prints structured output for agent/tool consumption.
• --debug enables selector and parser tracing to stderr.
• --interactive is enabled by default on TTY unless --json is used.

Commands

Auth

threads-cli auth status
threads-cli auth login
threads-cli auth whoami
threads-cli auth logout

Profile / Feed

threads-cli profile mine
threads-cli profile view --url https://www.threads.com/@someone
threads-cli profile latest --url https://www.threads.com/@true_comfort_
threads-cli profile my-posts --limit 10
threads-cli profile posts --url https://www.threads.com/@someone --limit 10
threads-cli profile list-posts --url https://www.threads.com/@someone --limit 10
threads-cli profile feed --limit 10

Interactive list view:

• Up/Down: move
• Enter: open detail view
• q: quit

Post

threads-cli post create --json-file /path/to/post.json
threads-cli post create \
  --title "제목" \
  --summary "한 줄 요약" \
  --source-url "https://example.com" \
  --image "/absolute/path/to/image.png" \
  --detail-line "핵심 1" \
  --detail-line "핵심 2" \
  --detail-line "핵심 3"

threads-cli post view --url https://www.threads.com/@someone/post/ABC123
threads-cli post edit --url https://www.threads.com/@me/post/ABC123 --text "수정 본문"
threads-cli post delete --url https://www.threads.com/@me/post/ABC123

Reply

threads-cli reply create \
  --url https://www.threads.com/@someone/post/ABC123 \
  --text "댓글 본문"

threads-cli reply create \
  --url https://www.threads.com/@someone/post/ABC123 \
  --source-url https://example.com \
  --detail-line "핵심 1" \
  --detail-line "핵심 2" \
  --detail-line "핵심 3"

threads-cli reply list --url https://www.threads.com/@someone/post/ABC123

Debug

threads-cli debug page-state --url https://www.threads.com/
threads-cli debug screenshot --url https://www.threads.com/
threads-cli debug post-parse --url https://www.threads.com/@someone/post/ABC123
threads-cli debug reply-parse --url https://www.threads.com/@someone/post/ABC123

Sample Output

Pretty output

$ threads-cli profile view --url https://www.threads.com/@true_comfort_
──────────────────────────────────────────────────────────────────────────────────────────────────
✓ profile.view
  url: https://www.threads.com/@true_comfort_
  text: @true_comfort_
  handle: @true_comfort_
  display_name: 김진녕
  followers: 43
  bio: Phd student in CSE
──────────────────────────────────────────────────────────────────────────────────────────────────

$ threads-cli reply list --url https://www.threads.com/@someone/post/ABC123
──────────────────────────────────────────────────────────────────────────────────────────────────
✓ reply.list
  url: https://www.threads.com/@someone/post/ABC123
  text: 메인 포스트 본문 미리보기...
  author: @someone
  view_count: 402
  reply_count: 3
  1. @user_one 첫 번째 답글
  2. @user_two 두 번째 답글
  3. @someone 세 번째 답글
──────────────────────────────────────────────────────────────────────────────────────────────────

JSON output

{
  "ok": true,
  "command": "reply.list",
  "profile": "default",
  "url": "https://www.threads.com/@someone/post/ABC123",
  "text_preview": "메인 포스트 본문 미리보기...",
  "full_text": "메인 포스트 본문 전체 텍스트",
  "author_handle": "@someone",
  "view_count": "402",
  "reply_count": 3,
  "reply_count_exact": 3,
  "reply_items": [
    {
      "author_handle": "@user_one",
      "text": "첫 번째 답글",
      "source": "embedded_json",
      "confidence": "high",
      "code": "REPLY1"
    }
  ]
}

Use --json for automation/agent integration, and the default pretty output for interactive terminal use.

JSON Input Examples

post create

{
  "profile_url": "https://www.threads.com/@true_comfort_",
  "delay_seconds": 45,
  "posts": [
    {
      "title": "메인 포스트 제목",
      "summary": "한 줄 요약",
      "source_url": "https://example.com/article",
      "detail_lines": [
        "핵심 포인트 1",
        "핵심 포인트 2",
        "핵심 포인트 3"
      ],
      "image_path": "/absolute/path/to/image.png"
    }
  ]
}

reply create

{
  "url": "https://www.threads.com/@someone/post/ABC123",
  "source_url": "https://example.com/article",
  "detail_lines": [
    "핵심 포인트 1",
    "핵심 포인트 2",
    "핵심 포인트 3"
  ]
}

Reading and Reply Parsing

threads-cli uses a layered strategy for post detail and reply extraction:

1. initial detail-page load
2. lazy-loading scroll passes
3. View more replies / View all replies button expansion
4. embedded JSON extraction
5. DOM fallback extraction

Reply data may come from different sources:

• embedded_json
• detail_dom
• fallback_dom

reply list --json and debug reply-parse --json expose:

• reply_count
• reply_count_exact
• reply_count_estimated
• reply_items
• sources
• scroll_passes
• expanded_more_replies

post view --json exposes:

• full_text
• author_handle
• timestamp
• view_count
• reply_count
• reply_items

profile view --json exposes:

• handle
• display_name
• bio
• follower_count
• following_count
• post_count
• external_url
• profile_pic_url

Debugging Guide

When reply counts do not match between list view and detail view:

1. run threads-cli reply list --url ... --json
2. run threads-cli debug reply-parse --url ... --json
3. compare:
   • reply_count_exact
   • reply_count_estimated
   • sources
   • scroll_passes
   • expanded_more_replies

Debug commands also save:

• page screenshot
• page HTML
• parser JSON dump

under the active profile debug directory.

Current Limitations

• Feed/profile list reply_count can still be best-effort.
• Detail-page reply counts can increase after scroll passes or “more replies” expansion.
• Threads web UI changes may require selector updates.
• post edit and post delete only work reliably on posts owned by the current logged-in account.
• following_count / post_count on profile view may be missing when the current page payload does not expose them clearly.

Roadmap

Not implemented yet:

• like / repost / quote
• notifications / mentions
• full reply delete/edit flows