# CLI files

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

## Commands

```sh
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.

```sh
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.