Skip to main content
A mount path is ephemeral. Server autosaves and permanent snapshots are the durable state behind it. A writable session also owns a local crash-safe journal, so the same machine can recover changes that had not reached the server when the mount stopped. Use these commands to inspect a session, resume it, browse its history, restore an earlier checkpoint or snapshot, or delete a file system.

​
Check Status

With unsaved changes, status lists dirty paths:
Two more lines appear as a session ages:
  • retained: counts files already published and kept locally as the byte cache. They are durable; the local copies only make reads and future autosaves fast. tl fs snapshot --clear trims cache entries covered by that snapshot while preserving later writes and ignored files.
  • ignored: counts local-only files that never enter an autosave or snapshot (build output and the like, per the file system’s ignore rules).
Add --json for machine-readable output.

​
Browse History

Autosaves provide a recent recovery window. Create a permanent, billed snapshot as part of the changed generation you need to keep:
Permanent snapshots are exempt from automatic retention. Snapshotting a clean mount is a quiet no-op and does not convert an existing autosave into a permanent record. Drop a permanent snapshot you no longer need with tl fs delete-snapshot agent-scratch <snapshot-id>.

​
List Sessions

tl fs ls with no argument lists your file systems.

​
Resume a Session

Unmounting keeps the session by default:
Remounting the file system on a machine that has a detached session resumes that session — unsaved local changes included. The new mount path can be different:
A session already mounted elsewhere mounts read-only if you mount its file system again. Unmount it there first to take writes.

​
Discard Local Changes

Throw away unsaved changes (and ignored files under the mount) with the mount:
Everything already published is untouched — autosave checkpoints and snapshots are immutable.

​
Restore

Restore the mount contents to an earlier checkpoint or snapshot:
You can restore to any autosave still inside the retention window or to any permanent snapshot. Restore does not rewrite history — it changes the working directory, and the next autosave records the restored state. Restoring over local changes requires --discard; create a snapshot first if they should survive permanently.

​
Repair a Session

If a session’s local state is ever inconsistent — a hard sandbox kill mid-write, an interrupted resume — tl fs doctor inspects it and can repair the local journal. Unmount first: doctor operates on a detached session and never contacts the server, so it cannot run under a live mount.
Pass --repair-journal to rebuild a damaged local journal. To re-point the session’s base as part of that repair, add --base <SNAPSHOT_OR_AUTOSAVE_ID> (or --base empty to reset to an empty base); --base requires --repair-journal. Doctor only touches local session state — durable history is never modified, because it never talks to the server.

​
Delete a File System

Pass -f to skip the confirmation. Deletion removes the file system, its history, and its sessions.