v1.0.0 STABLE

Thread Vault CLI

Python 3.13+ · Textual TUI · MIT License · ~280KB source

thread-vault-cli.zip · Latest release · All platforms

Installation Methods

Thread Vault CLI is distributed as source code. Install with uv (recommended) or standard pip.

Method 1 — uv (Recommended)

BASH — ALL PLATFORMS

                  # Install uv if not present
                  $ curl -LsSf
                  https://astral.sh/uv/install.sh | sh

                  # Clone & setup
                  $ git clone
                  https://github.com/grep-many/thread-vault-cli.git
                  $ cd thread-vault-cli
                  $ uv sync
                  $ uv run playwright install
                  --with-deps chromium

                  # Launch
                  $ uv run python -m app
                

Method 2 — pip + venv

BASH — ALL PLATFORMS

                  # Requires Python 3.13+
                  $ python -m venv .venv
                  $ source .venv/bin/activate
                  # Windows: .venv\Scripts\activate

                  $ pip install textual httpx
                  pydantic orjson rich typer playwright
                  $ playwright install chromium

                  # Launch
                  $ python -m app
                

Dependencies

🖥

textual ≥0.61.0

Modern TUI framework — powers the entire interactive terminal interface including screens, widgets, CSS theming, and event routing.

🌐

httpx ≥0.27.0

Async HTTP client for all Instagram API requests. Handles session cookies, CSRF tokens, and error classification.

✅

pydantic ≥2.7.0

Data validation for session models, scrape states, and all API response schemas.

⚡

orjson ≥3.10.0

High-performance JSON serialization for cache reads/writes and API response parsing.

🎨

rich ≥13.7.0

Rich text and formatting library used for console output, table rendering, and syntax highlighting in the TUI.

🌍

playwright ≥1.40.0

Browser automation for GUI login mode. Opens a headed Chromium window in a background thread to capture Instagram session cookies.

Release Notes

v1.0.0 CURRENT June 2026

Replaced pywebview with Playwright for cross-platform browser auth
Added threaded Playwright login — never blocks the Textual event loop
Inbox probe for session validation (more reliable than /current_user/ endpoint)
SQLite WAL mode with 5-second busy timeout and PRAGMA synchronous=NORMAL
Async queue-based pipeline with concurrent scrape + unsend workers
RateLimitManager with 5-stage exponential backoff and ±20% jitter
Complete 23-test offline suite with anyio + pytest
Session data isolation — zero persistence after logout/exit

Verify Installation

VERIFICATION

              # Run the full test suite (23 tests, fully offline)
              $ uv run pytest

              # Expected output
              # ======================== 23 passed in X.Xs
                =========================

              # Check Python version (requires 3.13+)
              $ python --version
            

🛡

Security note: Thread Vault CLI is distributed as open-source MIT-licensed code. Review the source in app/ before use. The application makes outbound requests exclusively to www.instagram.com — no telemetry, no analytics, no third-party data sharing.