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, or their SDK equivalents, 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; the SDK’s MountStatus.raw carries the same structured payload.

​
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 promotes its current automatic save to permanent retention in place, without uploading file bytes or creating a duplicate content version. It is a quiet no-op only when the current save is already permanent. 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 move the timeline backward or copy file bytes. It publishes a new automatic save whose content points at the selected historical root, then waits for the mounted directory and its kernel caches to converge before returning. Other writable and following mounts observe that new shared state normally. Restoring over local changes requires --discard; create a permanent snapshot first if they should survive.

​
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; the SDK clients delete without prompting. Deletion removes the file system, its history, and its sessions.