Docs menu
Docs/Developer interfaces/CLI/Files
View as Markdown

CLI files

File commands are path-first and bucket-scoped. Select a bucket directly or resolve it through an attached Site.

Commands

interfold files ls /data --bucket <bucket-id>
interfold files stat /web/index.html --site <site-id>
interfold files cat /web/index.html --site <site-id>
interfold files get /web/index.html ./index.html --site <site-id>
interfold files put ./index.html /web/index.html --site <site-id> \
  --content-type 'text/html; charset=utf-8'
interfold files rm /web/old.html --site <site-id>
interfold files history ls <file-id>
interfold files history cat <file-id> <version-id>
interfold files history get <file-id> <version-id> ./old-copy.bin
interfold files history restore <file-id> <version-id> <expected-current-version-id>
Command Description
ls List file metadata, optionally below a path prefix.
stat Print metadata without downloading content.
cat Write raw content to stdout.
get Download content to a local path.
put Create or replace a file.
rm Delete a file.
history ls List recent versions by stable file ID.
history cat Print a historical version.
history get Download a historical version atomically to a local path.
history restore Make historical content current as a new version.

ls prints files plus pagination. Pass --offset from pagination.nextOffset to continue a listing.

Each successful put returns a stable fileId and a new versionId. Use --if-match <current-version-id> on put to reject a stale write with HTTP 409. The flag is optional for older scripts. A restore always requires the current version ID and keeps the file’s current path and permissions.

Selecting storage

Use --bucket <id> for direct storage access. As a convenience, use --site <id>, --subdomain <name>, a project link, or a hosted URL when the bucket is attached to a Site.

File and Bucket API access always requires account authentication. Attaching a Site only maps /web/ files to hosted static URLs; it does not expose source, cron, data, database or migration assets, or arbitrary bucket objects.

interfold files get https://example.interfold.site/assets/logo.png ./logo.png

Live effects

Writing an attached /web/* file affects the hosted Site immediately. Writing /api/*.ts or /cron/*.ts also starts runtime deployment. Inspect the returned deployment object. It identifies the durable request with deploymentId, generation, desiredState, and status.

The API reconciles the saved generation immediately, so a normal write returns READY without waiting for a background job. A FAILED result means the file and requested runtime state were saved, but promotion did not finish. The recovery worker retries that exact generation on its next once-per-minute pass. Verify the runtime URL or scheduled result before depending on it.

Deleting function or cron source records desiredState: ABSENT before removing or pausing its deployed runtime. Failed cleanup is retried the same way.

On this page