Usage Guide

Complete reference for all Thread Vault CLI screens, controls, pipeline modes, rate limiting, and data management.

Thread Explorer Screen

After authentication, the Thread Explorer displays all your Instagram DM conversations. Threads are loaded from cache/inbox_cache.json on first load and ordered by last_activity_at descending (most recent first).

🔍

Search (`ctrl+f`)

Filter threads in real-time by title or participant username. The list updates instantly as you type.

🔄

Reload (`r`)

Fetches a fresh thread listing directly from the Instagram inbox API and refreshes both the display and the cache file.

Thread Detail Screen

After selecting a thread, the Thread Detail screen presents the three scope modes. Each mode is selectable with number keys 1, 2, or 3. Confirming the selection creates a FilterSet object and navigates to the Scrape Dashboard.

Scrape Dashboard (ScrapeReviewScreen)

The heart of Thread Vault. A multi-panel layout with target details, pipeline controls, a real-time message table, activity log, queue monitor, and rate-limit countdown widget.

⚡

Automatic Pipeline (`P`)

Starts both the scraper and unsend worker concurrently. The scraper pushes messages to the asyncio.Queue while the unsend worker consumes and processes them in parallel — maximum throughput.

⬇

Manual Scrape (`S`)

Runs the scraper worker alone. Messages are fetched, written to SQLite, and added to the table — but not unsent. Use when you want to inspect content before committing to deletion.

⊗

Manual Unsend (`U`)

Unsends only the messages currently checked (selected) in the table. Requires messages to be scraped first. Useful for selective deletion after reviewing content.

✗

Stop Pipeline

Sets the stop flag — both workers check this flag at each iteration and exit cleanly. Already-unsent messages are marked deleted in SQLite. The pipeline halts gracefully within the current request cycle.

Message Selection

Key	Action
`space`	Toggle selection on highlighted row
`ctrl+a`	Select all filtered items (or clear all if all are selected)
`ctrl+f`	Search/filter the message table by content or type
`x`	Reset pagination cursor — allows re-scraping from page 1

Rate Limiting

Thread Vault's RateLimitManager handles Instagram's 429 responses with a five-stage exponential backoff schedule. Each stage adds ±20% random jitter to avoid synchronized retry storms.

BACKOFF SCHEDULE (pipeline.py)
# Stage → Base wait → With ±20% jitter
            Stage 0: 30s → 24–36s
            Stage 1: 60s → 48–72s
            Stage 2: 120s → 96–144s
            Stage 3: 300s → 240–360s
            Stage 4: 600s → 480–720s # Max (stays here)

During a rate-limit wait, the dashboard shows a live countdown progress bar via the RateLimitWidget. The tick_cb callback fires every second with the remaining wait time. Pressing Stop during a wait cancels the wait immediately.

Data Management

SQLite Database Schema

data/vault.db — TABLES
-- Thread metadata
            threads (thread_id PK, thread_title, users JSON, last_activity_at)

            -- Scraped messages (archival)
            scraped_messages (seq AUTOINCREMENT, thread_id, message_id UNIQUE,
            item_type, payload JSON, is_deleted)

            -- Pagination state for resume
            scrape_progress (thread_id PK, cursor, finished)

            -- Unsend rate-limit state
            unsend_progress (thread_id PK, cooldown_idx)

            -- Indexes for fast queries
            idx_msg_thread_seq — (thread_id, seq)
            idx_msg_thread_deleted — (thread_id, is_deleted)
            idx_msg_thread_type — (thread_id, item_type)
          

Exporting Data Before Exit

⚠

All scraped data is deleted on exit. Export before leaving the dashboard if you need to retain records.

EXPORT — SQLITE CLI

# Export all scraped messages to CSV while the app is
              running
            $ sqlite3 data/vault.db -header -csv \
            "SELECT * FROM scraped_messages WHERE is_deleted=0;" \
            > export.csv

            # Export a specific thread
            $ sqlite3 data/vault.db -header -csv \
            "SELECT * FROM scraped_messages WHERE thread_id='YOUR_THREAD_ID';" \
            > thread_export.csv

            # Dump entire database
            $ sqlite3 data/vault.db .dump > full_backup.sql
          

Resuming Interrupted Scrapes

The scraper saves pagination cursors to scrape_progress in SQLite after each page. If a scrape is interrupted, re-running it on the same thread resumes from the last saved cursor automatically.

To force a full re-scrape from page 1, press X in the dashboard to reset the cursor state for the current thread.

🔒

Session Data Isolation: Upon exiting the Scrape Dashboard (Escape key) or logging out, Thread Vault deletes all rows from scraped_messages, scrape_progress, and unsend_progress, and deletes cache/session.json and cache/inbox_cache.json. This is a hard wipe — not a soft delete. The threads table persists between sessions for the thread directory cache.