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 a folder-layout 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 document’s selected layout
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. Title rules can refresh automatic or rule-owned titles, but Refile never overwrites a title owned by a person.

​
Filing-tree changes

Custom taxonomy imports merge additively; they do not reset filing or move existing documents to Inbox. Reviewed built-in/composed changes may rename a category in place, preserving its row ID and every live or recoverable document reference. A proposed mapping can instead use a free same-decade code or skip the incoming category. A tree change never touches automations. Refile then runs only enabled, active rules. It remains a separate explicit operation over current configuration and cannot bypass an unresolved mapping. It is not a taxonomy reset or a new document version. 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. Document 147 can move from category address S01.13 to S01.14, never S02 through category assignment; its installation-global ID and __147 default filename suffix stay stable. S01.13 remains the address of category 13 rather than a stale document alias.

​
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.