Maintenance commands

pplx-export's maintenance subcommands keep an existing archive healthy: re-render pages after renderer fixes, backfill assets / credit usage / mode metadata, tombstone remotely deleted threads, and rebuild the relation graph. Most are offline-first; their online phases follow the same pacing discipline as batch (see rate-limiting.md). All of them accept the common options (--account, --out, --cookies-from, --transport, …).

• Local-archive retention principle: no maintenance command ever deletes or moves archived thread content — the archive is the backup.
• The offline commands (re-render, relations, sync-space, spaces without --fetch-meta, and the default phases below) need no transport at all; see ../design/offline-operations.md.

re-render

Regenerate conversation.md and turns/ from the archived raw JSON (raw_entries.json / raw_blocks.json) after renderer fixes — zero network, and every other file is left untouched.

Flag	Meaning	Default
--limit N	Process only the first N thread directories	all
--dry-run	List the directories that would be processed, write nothing	off
--thread-json	Also add/remove the interruptions and answer_variants keys in thread.json in place	off

Key behaviors:

• Rebuilds turns offline with the same pipeline as export: parsing, ordering by created_us, citation dedup, and — for computer/council — workflow blocks, sub-agent mapping and the unconsumed-background appendix.
• Only conversation.md and turns/turn_*.md are (re)written; sources*, assets/, report.md and thread.json stay as-is. Stale turn_*.md files numbered above the current turn count are deleted — nothing else, so unchanged files keep their mtime.
• --thread-json writes only when the content actually changes; newly added/changed answer_variants raise an ANSWER_VARIANT_DETECTED warning and are appended to index/answer_variants_log.jsonl (idempotent reruns don't spam).
• Thread directories without raw_entries.json are skipped and counted.

pplx-export re-render --limit 20 --thread-json --dry-run

assets-backfill

Remediate assets that were archived without a signed URL — three staged remedies: re-fetch missing blocks, offline inline extraction, and optional online refresh.

Flag	Meaning	Default
--fetch-blocks	First re-fetch missing raw_blocks.json and their signed-URL assets (online)	off
--online	Enable the online refresh of missing/stale assets	off (offline inline extraction only, zero requests)
--limit N	Process only the first N thread directories	all

Key behaviors:

• Default phase (offline, zero requests): extract inline assets (ASSET_DIFF / CODE_ASSET) from raw_blocks.json into assets/files/*.md, and register cloud-workspace handle kinds (DOC_FILE / CODE_FILE / UNKNOWN — no download channel yet) in assets/assets_manifest.json. Idempotent: known records are deduped by uuid, then file_handle; multi-version same-name files get a uuid short-suffix so reruns don't collide.
• --fetch-blocks (online): re-fetch missing raw_blocks.json for deep-research/computer/council/study threads plus their downloadable assets; threads are grouped by account folder with a lazily-built adapter per account (cookies switch automatically), 3s between threads.
• --online: for manifest versions whose downloaded_to is missing/stale, fetch a fresh signed URL via /rest/assets/<uuid>/data (API calls serial, 3s apart), then re-download from the CDN (6 concurrent threads, no delay — CDN, not API). A 404 ASSET_NOT_FOUND sets the asset_expired terminal flag; a cross-account 403 is retried once with the account that owns the archive folder.
• The manifest count is recomputed as the total number of versions on every write-back.

pplx-export assets-backfill --fetch-blocks --online --limit 30 --account alice

usage-backfill

Backfill per-thread credit usage (credits/thread-usage) for all of the account's archived threads into index/credit_usage_<account>.json.

Flag	Meaning	Default
--limit N	Process only the first N threads	all

Key behaviors:

• One GET per archived thread (thread_id = the thread's psc_uuid), 3s apart; idempotent — threads already present in the output file are skipped.
• A 403 (thread_usage_forbidden, i.e. a cross-account thread) is recorded as error and never retried; other failures are left for the next run. Progress is saved every 25 processed threads.
• Multi-account: run once per account with --account — the cookies switch automatically between runs.

pplx-export usage-backfill --account alice

search-mode-backfill

Backfill the platform-authoritative search_mode field into each row of index/library_<account>.json, so batch --mode can filter exactly instead of relying on heuristics.

Flag	Meaning	Default
--limit N	Process only the first N pending rows	all
--offline	Local extraction only — rows without local raw data wait for the next round, no online fallback	off
--delay-min SEC	Lower bound of the random interval between online-fallback threads	10
--delay-max SEC	Upper bound of the random interval between online-fallback threads	20

Key behaviors:

• Stores the platform raw value (SEARCH / RESEARCH / ASI / AGENTIC_RESEARCH / STUDY / STUDIO…); a thread carrying multiple values keeps the most specific one by computer > council > study > deep-research > search.
• Local-first: archived threads resolve from raw_entries.json with zero network — a fully local run never even builds a transport (not even a session probe).
• Online fallback only for rows without local raw data: GET /rest/thread/<uuid> with a 10–20s random interval; rows in expired terminal state are skipped and recorded; threads newly found expired/deleted online are marked in batch_state.json to spare future requests.
• Idempotent and resumable: rows that already have search_mode are skipped, progress is saved every 25 rows, and later index refreshes preserve the enrichment (merged back by entryUUID).

pplx-export search-mode-backfill --account alice --offline

sync-deleted

Identify threads that vanished from the remote library (deleted by the user or the platform) and tombstone them — it never deletes or moves any archive file.

Flag	Meaning	Default
--online	Verify each candidate online	off (offline dry-run: list candidates only)
--limit N	Process only the first N candidates	all
--delay-min SEC	Lower bound of the random interval between candidates	10
--delay-max SEC	Upper bound of the random interval between candidates	20

Key behaviors:

• Candidate detection is offline and cross-account: a thread with batch_state status ok that is missing from the entryUUID union of all index/library_*.json files becomes a candidate — any single index containing it counts as alive, so threads exported cross-account via shared spaces are not false-positived. When no usable index exists, everything is safely skipped with a hint to run index first.
• Default is an offline dry-run: it lists candidates and safe-skip reasons — zero network, zero writes.
• --online verifies each candidate with GET /rest/thread/<uuid> under the account recorded in thread.json export_via (cookies switch automatically per candidate).
• Confirmed by ENTRY_DELETED / ENTRY_EXPIRED / HTTP 404 → batch_state marks the terminal state deleted (same semantics as expired: never retried, --force does not re-export; see incremental-sync.md) and each of the thread's thread.json files gets a remote_deleted timestamp in place (idempotent — an existing key is kept).
• Thread still exists → false positive: reported as-is with a hint to re-run index, nothing changed. Transport errors back off to the next round; 3 consecutive auth failures abort the run before anything gets mis-marked.

pplx-export sync-deleted
pplx-export sync-deleted --online --limit 20

The first run lists candidates (offline dry-run); the second verifies them online and tombstones the confirmed ones.

relations

Rebuild the conversation relation graph from the exported threads → relations/edges.jsonl plus a human-readable relations/graph.md under the archive root.

Flag	Meaning	Default
(common options only; only --out matters)

Key behaviors:

• Purely offline, zero network, read-only against the archive: it reuses re-render's offline rebuild pipeline (raw_entries.json / raw_blocks.json), so sub_agents, query_source and citation signals are all available for edge detection.
• Threads without raw data degrade to a thread.json + conversation.md shell — only same_space and bare-uuid reference edges can fire for them.

pplx-export relations

debug-js

Execute a JavaScript snippet in the current browser page context via the local WebBridge daemon (127.0.0.1:10086) and print the result as JSON — a debugging escape hatch.

Flag	Meaning	Default
JS代码 (positional)	JavaScript code to evaluate in the page context (the literal argparse metavar)	required

Key behaviors:

• Requires the WebBridge daemon to be reachable and the target Perplexity page open in the browser; the snippet runs with the page's own session.
• The printed JSON is truncated at 5000 characters.

pplx-export debug-js 'document.title'