Skip to main content
Refile applies the current filing configuration to existing live documents. Use it after changing a filing-tree preset, document-added automations, or the rendered storage-path template.

​
What it does

For each document live in the selected system when the run began, Refile can:
  1. rerun enabled document_added automations against current metadata
  2. enqueue a durable render job for the current storage-path template
It does not rerun extraction, OCR, local archive matching, or the LLM classifier. Use a selected rescan for those operations. Trashed documents are skipped. Automation effects are additive. Removing an automation does not undo tags or other metadata it wrote earlier. Built-in assignment actions generally converge when repeated.

​
Filing-tree changes

Later imports and built-in preset applications merge additively; they do not reset filing or move existing documents to Inbox. Only safe unconfigured bootstrap setup may replace the initial tree. Preset refile cannot bypass merge protection or silently discard collisions; use custom import preview with explicit remaps/skips for conflicting categories. Refile is a separate explicit operation over current configuration. It can rerun enabled filing automations and/or enqueue rendered paths; it is not a taxonomy reset or a new document version. Existing disabled preset originals and user-owned forks survive preset reapplication. Default JD and flat filenames now begin with the document’s recorded created date, falling back to added date and then undated, retaining title and ID suffix. To update old fallback paths without automation reruns, use suchi refile --system S01 --skip-automations. After introduction, the stable rendered/<SYS>/ root is enforced outside explicit custom templates and each system’s 00-09 System index namespace is reserved. Original blobs and extraction/classification state are unchanged. First prefixed import already queues render-only moves for the original system; it does not rerun classification. Refile changes category/location within a system, not system ownership. S01.13.147 can become S01.14.147, never S02 via category assignment; the installation-global ID stays 147 and the old address becomes stale.

​
Admin API

POST /api/admin/refile?system=S01 runs both passes for every owner in S01 by default:
The response reports work attempted, not a transactional archive-wide commit:
Failures on one document are counted and logged while the sweep continues. Render work runs asynchronously through the durable queue.

​
CLI

Omitting --system (or the API query) selects original system 1; it never sweeps all systems. API administration still requires an active session administrator. The CLI opens the same database directly. It can run while suchi serve is active: document IDs are snapshotted at the start, and uploads arriving later use the current automations and render configuration through normal ingest.

​
Operational notes

  • A large run can enqueue many render jobs. Monitor the Approvals screen or GET /api/tasks/?include=jobs for failures.
  • Refile only considers the documents live at its start. Newly ingested documents do not need inclusion because they use current configuration.
  • Repeating a render pass is supported; the rendered tree is a rebuildable projection, not the metadata source of truth.
See Automations, Filing trees, and Pipeline versions.