CLI reference
Discover the Folderbase command surface and its stable machine-readable interface.
The folderbase executable is the reference interface to Folderbase Core.
Discover commands
folderbase --help
folderbase protocol contract --jsonFolderbase is a Beta product. protocol contract --json advertises the named
stable machine contract inside that Beta; human-readable --help can include
additional experimental commands and must not be parsed as a compatibility
surface.
Primary command families
| Command | Interface status | Purpose |
|---|---|---|
inspect | Stable JSON v1 | Read folder metadata and boundaries without mutation. |
attest | Stable JSON v1 | Verify one exact Folderbase root without mutation. |
init | Stable JSON v1 | Preview or add the native protocol surface. Template options remain experimental. |
upgrade | Stable JSON v1 | Preview or apply the explicit legacy-root upgrade. |
validate | Stable JSON v1 | Check protocol records and report diagnostics. |
workspace | Stable JSON v1 | List, read, and save bounded UTF-8 workspace files. |
protocol | Stable JSON v1 | Advertise the contract or check portable records. |
query | Unstable Beta optional capability | Filter a bounded metadata inventory; it does not search file contents. Requires folderbase.query-index@0.1.0. |
index | Unstable Beta optional capability | Inspect or explicitly rebuild the disposable private metadata index. Requires folderbase.query-index@0.1.0. |
daemon | Experimental Beta optional capability | Serve one root-pinned query/index session over stdio JSON Lines. Requires folderbase.daemon-stdio@0.1.0. |
template | Stable optional capability | Preview or apply one exact additive Template 0.2 package. Requires folderbase.template-expansion@0.1.0. |
change-set | Stable optional capability | Materialize scoped ordinary folders, propose immutable work, assess conflicts, and apply or replay it. Requires folderbase.change-set@0.1.0. |
folder-scope | Stable optional capability | Produce Core-owned continuity evidence for one exact selected ordinary folder before its first durable share. Requires folderbase.folder-scope-evidence@0.1.0. |
reconstruct | Stable optional capability | Reconstruct one exact retained Folderbase Version into one absent ordinary root. Requires folderbase.root-reconstruction@0.1.0. |
migrate | Experimental JSON | Analyze and stage reviewed restructuring. |
transform | Experimental JSON | Run the durable multi-process transform workflow. |
version | Experimental JSON | Capture, inspect, and restore immutable local file versions. |
Machine-readable calls
Use --json on supported commands. Successful JSON output is written to stdout. Diagnostics and progress that are not part of the result belong on stderr.
See CLI JSON v1 for the compatibility rules. Query and index commands use their own closed wire contract; see the query/index reference. They are optional and are not required by sync, Cloud durability, sharing, or ordinary agent workspace access. Long-lived App and agent integrations should also read the daemon stdio reference. Template plan/apply uses a separate stable optional contract; see the template expansion reference. Scoped checkout and apply use another stable optional contract; see the Change Set reference. Exact-folder first-share evidence has its own stable optional contract; see the Folder Scope evidence reference. Exact retained-Version reconstruction uses its own stable optional contract; see the root reconstruction reference. TypeScript, Swift, native apps, and remote agent VMs should use the process adapter contract instead of reading engine-owned records.