# Files (/cli/files)

Browse workspace files, read or write content, manage versions, and configure sharing.

`sim files` is also spelled `sim file`.

These commands accept the [global options](/cli/commands#global-options).

## Browse and inspect \[#browse-and-inspect]

### List file resources and child folders together \[#list-file-resources-and-child-folders-together]

```bash
sim files ls [path] [options]
```

**Arguments**

| Argument | Required | Description |
| - | - | - |
| `path` | No | Folder path to list; defaults to the root folder |

**Options**

| Option | Required | Description |
| - | - | - |
| `--search <text>` | No | Filter folders and resources by name. |
| `--limit <n>` | No | Maximum combined items to return (0 for everything). Defaults to `0`. |

API request and response schemas: [listFiles](/api-reference/files/listFiles), [listFileFolders](/api-reference/files/listFilesFolders).

### List files \[#list-files]

```bash
sim files list [options]
```

**Options**

| Option | Required | Description |
| - | - | - |
| `--folder <value>` | No | Folder path as shown in the app; the leading / is optional. |
| `--recursive` | No | Include subfolders in the folder filter. Defaults to true when searching and false otherwise. Ignored without a folder filter. |
| `--no-recursive` | No | Send --recursive as false. |
| `--scope <value>` | No | Which lifecycle set to list: `active` (default) for live files, `archived` for files a delete soft-deleted. `folderPath` resolves against active folders only, so pairing it with `scope=archived` returns an empty page when the containing folder was archived too. Accepted values: `active`, `archived`. |
| `--search <value>` | No | Case-insensitive substring match against the file name. |
| `--sort-by <value>` | No | Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`. Defaults to "uploadedAt". Accepted values: `name`, `size`, `uploadedAt`, `updatedAt`. |
| `--sort-order <value>` | No | Sort direction. Defaults to "asc". Accepted values: `asc`, `desc`. |
| `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `0`. |

API request and response schemas: [listFiles](/api-reference/files/listFiles).

### Search file content \[#search-file-content]

```bash
sim files search [options]
```

**Options**

| Option | Required | Description |
| - | - | - |
| `--query <value>` | Yes | Regular expression, or exact text when `mode` is `exact`. |
| `--mode <value>` | No | How `query` is read. Defaults to "regex". Accepted values: `exact`, `regex`. |
| `--max-results <value>` | No | Maximum matching lines to return. Defaults to 50. |
| `--folder <value...>` | No | Folders to search, by path as shown in the app; omit to search the whole workspace (space-separated, or @path / @- with one value per line; @@value for a literal leading @). |
| `--include-subfolders` | No | Whether each folder scope includes nested folders; on by default. |
| `--no-include-subfolders` | No | Send --include-subfolders as false. |

API request and response schemas: [searchFileContent](/api-reference/files/searchFileContent).

### Show file metadata and sharing status \[#show-file-metadata-and-sharing-status]

```bash
sim files describe <fileId> [options]
```

**Arguments**

| Argument | Required | Description |
| - | - | - |
| `fileId` | Yes | File identifier, or the VFS path of a live file: `files/<folder>/<name>`. Pass the id when two files in a folder have names that display alike. |

**Options**

| Option | Required | Description |
| - | - | - |
| `--scope <value>` | No | Which lifecycle set to read from: `active` (default) resolves live files only and returns `404` for a file a delete soft-deleted; `archived` also resolves soft-deleted files, so metadata stays readable before the file is restored. Authorization is identical for both. Accepted values: `active`, `archived`. |

API request and response schemas: [getFile](/api-reference/files/getFile).

## Upload, create, and read \[#upload-create-and-read]

### Upload a file to the workspace \[#upload-a-file-to-the-workspace]

```bash
sim files upload <path> [options]
```

**Arguments**

| Argument | Required | Description |
| - | - | - |
| `path` | Yes | Local file to upload |

**Options**

| Option | Required | Description |
| - | - | - |
| `--folder <path>` | No | Folder path as shown in the app; defaults to the root folder. |
| `--name <name>` | No | Store it under a different name. |

API request and response schemas: [createFileUpload](/api-reference/files/createFileUpload), [createFileUploadPartUrls](/api-reference/files/createFileUploadPartUrls), [completeFileUpload](/api-reference/files/completeFileUpload), [abortFileUpload](/api-reference/files/abortFileUpload).

### Create file \[#create-file]

```bash
sim files create [options]
```

**Options**

| Option | Required | Description |
| - | - | - |
| `--name <value>` | Yes | File name, including its extension. Path separators and dot segments are rejected. |
| `--content-type <value>` | No | MIME type. When omitted, it is inferred from the file extension. |
| `--folder <value>` | No | Folder path as shown in the app; the leading / is optional. |
| `--content <value>` | No | Initial file content. Omit or send an empty string for a zero-byte file. The complete JSON request is capped at 10 MiB, including encoding and the envelope; the separate decoded-file limit is 50 MiB. For larger payloads, use `sim files upload <path>`. Defaults to "". |
| `--encoding <value>` | No | Encoding of the content field. Defaults to "utf-8". Accepted values: `utf-8`, `base64`. |

API request and response schemas: [createFile](/api-reference/files/createFile).

### Download a file’s content to stdout or a local file \[#download-a-files-content-to-stdout-or-a-local-file]

```bash
sim files get <fileId> [options]
```

**Arguments**

| Argument | Required | Description |
| - | - | - |
| `fileId` | Yes | File whose content to read: its id, or its `files/<folder>/<name>` VFS path |

**Options**

| Option | Required | Description |
| - | - | - |
| `-o, --output-file <path>` | No | Write content to a file instead of stdout. |
| `--force` | No | Overwrite --output-file if it already exists. |

API request and response schemas: [downloadFile](/api-reference/files/downloadFile).

### Read a file’s text content as JSON or YAML \[#read-a-files-text-content-as-json-or-yaml]

```bash
sim files read <fileId> [options]
```

**Arguments**

| Argument | Required | Description |
| - | - | - |
| `fileId` | Yes | File identifier, or the file’s VFS path: `files/<folder>/<name>`, or `uploads/<name>` for a Chat upload. |

**Options**

| Option | Required | Description |
| - | - | - |
| `--max-bytes <value>` | No | Optional ceiling on the source bytes fed to the parser, lowering but never raising the server limit. |
| `--offset <value>` | No | First line to return, 1-based; 0 also starts at the first line. Absent starts at the first line. |
| `--limit <value>` | No | How many lines to return from `offset`. Absent reads to the end. |

API request and response schemas: [readFileText](/api-reference/files/readFileText).

## Edit and organize \[#edit-and-organize]

### Apply one exact or anchor-based edit to a text file \[#apply-one-exact-or-anchor-based-edit-to-a-text-file]

```bash
sim files edit <fileId> [options]
```

**Arguments**

| Argument | Required | Description |
| - | - | - |
| `fileId` | Yes | File identifier. |

**Options**

| Option | Required | Description |
| - | - | - |
| `--edit <json\|@file>` | Yes | One edit object: {"mode":"search\_replace","search":"old","content":"new","replaceAll":false}, {"mode":"replace\_between","beforeAnchor":"start line","afterAnchor":"end line","content":"new"}, {"mode":"insert\_after","anchor":"line","content":"new"}, or {"mode":"delete\_between","startAnchor":"first line deleted","endAnchor":"ending line kept"}. Anchored modes also accept occurrence starting at 1 (JSON, or @path / @- to read a file or stdin). |
| `--expected-revision <value>` | No | Revision from Get file metadata or an earlier write; the request is refused with `409` when the content moved on. |

API request and response schemas: [editFileContent](/api-reference/files/editFileContent).

### Replace a file’s contents \[#replace-a-files-contents]

```bash
sim files set-content <fileId> [options]
```

**Arguments**

| Argument | Required | Description |
| - | - | - |
| `fileId` | Yes | File identifier. |

**Options**

| Option | Required | Description |
| - | - | - |
| `--content <value>` | Yes | Complete replacement content for the file. The complete JSON request is capped at 10 MiB, including UTF-8 encoding, escaping, base64, and the envelope. The separate decoded-file limit is 50 MiB. Small patches can edit a larger stored text file without sending its full content. |
| `--encoding <value>` | No | Content encoding. Defaults to "utf-8". Accepted values: `utf-8`, `base64`. |
| `--expected-revision <value>` | No | Revision from Get file metadata or an earlier write; the request is refused with `409` when the content moved on. |

API request and response schemas: [updateFileContent](/api-reference/files/updateFileContent).

### Rename a file \[#rename-a-file]

```bash
sim files rename <fileId> [options]
```

**Arguments**

| Argument | Required | Description |
| - | - | - |
| `fileId` | Yes | File identifier, or the VFS path of a live file: `files/<folder>/<name>`. Pass the id when two files in a folder have names that display alike. |

**Options**

| Option | Required | Description |
| - | - | - |
| `--name <value>` | Yes | New file name, including its extension. |

API request and response schemas: [renameFile](/api-reference/files/renameFile).

### Move files into another folder \[#move-files-into-another-folder]

```bash
sim files move [options]
```

Also available as `sim files mv`.

**Options**

| Option | Required | Description |
| - | - | - |
| `--file-ids <value...>` | Yes | File identifiers to update. (space-separated, or @path / @- with one value per line; @@value for a literal leading @). |
| `--to <value>` | No | Destination folder path; omit for root. |

API request and response schemas: [moveFileItems](/api-reference/files/moveFileItems).

### Unzip an archive into a new folder beside it \[#unzip-an-archive-into-a-new-folder-beside-it]

This writes every file in the archive into the workspace.

```bash
sim files unzip <fileId> [options]
```

**Arguments**

| Argument | Required | Description |
| - | - | - |
| `fileId` | Yes | File identifier. |

**Options**

| Option | Required | Description |
| - | - | - |
| `-y, --yes` | Yes | Confirm this operation. |

API request and response schemas: [unzipFile](/api-reference/files/unzipFile).

## Sharing \[#sharing]

### Show a file’s share settings \[#show-a-files-share-settings]

```bash
sim files share get <fileId>
```

**Arguments**

| Argument | Required | Description |
| - | - | - |
| `fileId` | Yes | File identifier. |

API request and response schemas: [getFileShare](/api-reference/files/getFileShare).

### Enable or disable sharing for a file \[#enable-or-disable-sharing-for-a-file]

OAuth login or personal API key required.

```bash
sim files share set <fileId> [options]
```

**Arguments**

| Argument | Required | Description |
| - | - | - |
| `fileId` | Yes | File identifier. |

**Options**

| Option | Required | Description |
| - | - | - |
| `--is-active <true\|false>` | Yes | Whether the share should resolve. Disabling preserves the token and the whole access configuration, so re-enabling restores the share as it was; enabling rewrites the credentials the resulting mode does not use. Accepted values: `true`, `false`. |
| `--auth-type <value>` | No | How access to the share is gated. The stored mode is kept when omitted. Enabling `public` clears the stored password and empties `allowedEmails`; `password` empties `allowedEmails`; `email` and `sso` clear the stored password. Accepted values: `public`, `password`, `email`, `sso`. |
| `--password <value>` | No | Password of 15 to 1024 characters for a password-gated share. Kept when omitted; enabling `password` with neither a supplied nor a stored password is a 400. Taken literally, except that a request from the Sim agent resolves a whole-value `{{ENV_VAR}}` reference to that variable before the rules apply. |
| `--allowed-emails <value...>` | No | Allowed addresses or `@domain` patterns for email and SSO shares. Kept when omitted; enabling `email` or `sso` with an empty resulting list is a 400. (space-separated, or @path / @- with one value per line; @@value for a literal leading @). |

API request and response schemas: [upsertFileShare](/api-reference/files/upsertFileShare).

## Versions \[#versions]

### List the recorded versions of a file \[#list-the-recorded-versions-of-a-file]

```bash
sim files versions list <fileId> [options]
```

**Arguments**

| Argument | Required | Description |
| - | - | - |
| `fileId` | Yes | File identifier. |

**Options**

| Option | Required | Description |
| - | - | - |
| `--sort-by <value>` | No | Field used to sort the result. Defaults to "version". Accepted values: `version`. |
| `--sort-order <value>` | No | Sort direction. Defaults to "desc". Accepted values: `asc`, `desc`. |
| `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `100`. |
| `--cursor <value>` | No | Continue from nextCursor returned by a previous result. |

API request and response schemas: [listFileVersions](/api-reference/files/listFileVersions).

### Show the metadata of one version of a file \[#show-the-metadata-of-one-version-of-a-file]

```bash
sim files versions describe <fileId> <version>
```

**Arguments**

| Argument | Required | Description |
| - | - | - |
| `fileId` | Yes | File identifier. |
| `version` | Yes | Version number. |

API request and response schemas: [getFileVersion](/api-reference/files/getFileVersion).

### Read the text content of one version of a file as JSON or YAML \[#read-the-text-content-of-one-version-of-a-file-as-json-or-yaml]

```bash
sim files versions read <fileId> <version> [options]
```

**Arguments**

| Argument | Required | Description |
| - | - | - |
| `fileId` | Yes | File identifier. |
| `version` | Yes | Version number. |

**Options**

| Option | Required | Description |
| - | - | - |
| `--max-bytes <value>` | No | Optional ceiling on the source bytes fed to the parser, lowering but never raising the server limit. |
| `--offset <value>` | No | First line to return, 1-based; 0 also starts at the first line. Absent starts at the first line. |
| `--limit <value>` | No | How many lines to return from `offset`. Absent reads to the end. |

API request and response schemas: [readFileVersionText](/api-reference/files/readFileVersionText).

### Download the content of one version of a file \[#download-the-content-of-one-version-of-a-file]

```bash
sim files versions download <fileId> <version> [options]
```

**Arguments**

| Argument | Required | Description |
| - | - | - |
| `fileId` | Yes | File identifier. |
| `version` | Yes | Version number. |

**Options**

| Option | Required | Description |
| - | - | - |
| `-o, --output-file <path>` | No | Write content to a file instead of stdout. |
| `--force` | No | Overwrite --output-file if it already exists. |

API request and response schemas: [downloadFileVersion](/api-reference/files/downloadFileVersion).

### Make a previous version of a file current again \[#make-a-previous-version-of-a-file-current-again]

```bash
sim files versions revert <fileId> <version> [options]
```

**Arguments**

| Argument | Required | Description |
| - | - | - |
| `fileId` | Yes | File identifier. |
| `version` | Yes | Version number. |

**Options**

| Option | Required | Description |
| - | - | - |
| `--expected-current-version <value>` | No | Revert only while this is still the current version; otherwise the request fails with `409`. Omit to revert whatever is current. Collaborative edits and repeated workflow writes that fold into the current version keep its number, so prefer `expectedRevision` to guard content. |
| `--expected-revision <value>` | No | Revert only while the file still holds the content this revision names, as returned by Get file metadata or an earlier write; otherwise the request fails with `409`. Unlike a version number, it also catches edits that folded into the current version. |

API request and response schemas: [revertFileVersion](/api-reference/files/revertFileVersion).

### Permanently delete a previous version of a file \[#permanently-delete-a-previous-version-of-a-file]

This permanently removes the version from history and schedules deletion of its stored content; storage cleanup may retry in the background.

```bash
sim files versions delete <fileId> <version> [options]
```

**Arguments**

| Argument | Required | Description |
| - | - | - |
| `fileId` | Yes | File identifier. |
| `version` | Yes | Version number. |

**Options**

| Option | Required | Description |
| - | - | - |
| `-y, --yes` | Yes | Confirm this operation. |

API request and response schemas: [deleteFileVersion](/api-reference/files/deleteFileVersion).

## Archive and restore \[#archive-and-restore]

### Delete file \[#delete-file]

This archives the file.

```bash
sim files delete <fileId> [options]
```

**Arguments**

| Argument | Required | Description |
| - | - | - |
| `fileId` | Yes | File identifier, or the VFS path of a live file: `files/<folder>/<name>`. Pass the id when two files in a folder have names that display alike. |

**Options**

| Option | Required | Description |
| - | - | - |
| `-y, --yes` | Yes | Confirm this operation. |

API request and response schemas: [deleteFile](/api-reference/files/deleteFile).

### Delete several files at once \[#delete-several-files-at-once]

This archives the listed files; restore them with `files restore`.

```bash
sim files batch-delete [file-ids...] [options]
```

**Arguments**

| Argument | Required | Description |
| - | - | - |
| `file-ids...` | No | Files to delete, each by identifier or by the VFS path of a live file: `files/<folder>/<name>`. Pass the id when two files in a folder have names that display alike. At most 100 entries may be paths. Same as --file-ids. |

**Options**

| Option | Required | Description |
| - | - | - |
| `--file-ids <value...>` | No | Files to delete, each by identifier or by the VFS path of a live file: `files/<folder>/<name>`. Pass the id when two files in a folder have names that display alike. At most 100 entries may be paths. (space-separated, or @path / @- with one value per line; @@value for a literal leading @) (required, or pass the values as arguments). |
| `-y, --yes` | Yes | Confirm this operation. |

API request and response schemas: [bulkDeleteFiles](/api-reference/files/bulkDeleteFiles).

### Restore an archived file \[#restore-an-archived-file]

```bash
sim files restore <fileId>
```

**Arguments**

| Argument | Required | Description |
| - | - | - |
| `fileId` | Yes | File identifier. |

API request and response schemas: [restoreFile](/api-reference/files/restoreFile).

## Folders \[#folders]

### List folders \[#list-folders]

```bash
sim files folders list [options]
```

Also available as `sim files folders ls`.

**Options**

| Option | Required | Description |
| - | - | - |
| `--parent <value>` | No | Direct parent folder path. |
| `--search <value>` | No | Case-insensitive substring match against the folder name. |
| `--sort-by <value>` | No | Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`. Defaults to "name". Accepted values: `name`, `createdAt`, `updatedAt`. |
| `--sort-order <value>` | No | Sort direction. Defaults to "asc". Accepted values: `asc`, `desc`. |
| `--scope <value>` | No | Which lifecycle set to list: `active` (default) returns live folders only; `archived` returns folders a recursive delete soft-deleted, which is how a caller finds a path to hand to the folder restore. Authorization is identical for both. Accepted values: `active`, `archived`. |
| `--recursive <value>` | No | Whether parentPath includes every descendant instead of direct children only. Accepted values: `true`, `1`, `yes`, `on`, `y`, `enabled`, `false`, `0`, `no`, `off`, `n`, `disabled`. |
| `--depth <value>` | No | Deepest level below parentPath to include when recursive is true. |

API request and response schemas: [listFileFolders](/api-reference/files/listFilesFolders).

### Create a file folder at a path \[#create-a-file-folder-at-a-path]

```bash
sim files folders create <path>
```

**Arguments**

| Argument | Required | Description |
| - | - | - |
| `path` | Yes | Folder path as shown in the app; the leading / is optional |

API request and response schemas: [createFileFolder](/api-reference/files/createFilesFolder).

### Delete folder \[#delete-folder]

This archives the file folder and, when recursive, everything inside it.

```bash
sim files folders delete <path> [options]
```

**Arguments**

| Argument | Required | Description |
| - | - | - |
| `path` | Yes | Folder path as shown in the app; the leading / is optional |

**Options**

| Option | Required | Description |
| - | - | - |
| `--recursive` | No | Archive the folder and its descendants. Defaults to "false". |
| `-y, --yes` | Yes | Confirm this operation. |

API request and response schemas: [deleteFileFolder](/api-reference/files/deleteFilesFolder).

### Restore an archived file folder \[#restore-an-archived-file-folder]

```bash
sim files folders restore <path>
```

**Arguments**

| Argument | Required | Description |
| - | - | - |
| `path` | Yes | Folder path as shown in the app; the leading / is optional |

API request and response schemas: [restoreFileFolder](/api-reference/files/restoreFilesFolder).

### Rename or move a file folder \[#rename-or-move-a-file-folder]

```bash
sim files folders move <path> <destination>
```

Also available as `sim files folders mv`.

**Arguments**

| Argument | Required | Description |
| - | - | - |
| `path` | Yes | Folder path as shown in the app; the leading / is optional |
| `destination` | Yes | Folder path as shown in the app; the leading / is optional |

API request and response schemas: [relocateFileFolder](/api-reference/files/relocateFilesFolder).

### Create a file directory at a path \[#create-a-file-directory-at-a-path]

```bash
sim files mkdir <path>
```

**Arguments**

| Argument | Required | Description |
| - | - | - |
| `path` | Yes | Folder path to create; the leading / is optional |

API request and response schemas: [createFileFolder](/api-reference/files/createFilesFolder).

## Other commands \[#other-commands]

### Copy file items \[#copy-file-items]

OAuth login or personal API key required.

```bash
sim files copy [options]
```

**Options**

| Option | Required | Description |
| - | - | - |
| `--source <json\|@file>` | Yes | Source owner and selected fileIds or folderIds (JSON, or @path / @- to read a file or stdin). |
| `--destination <json\|@file>` | Yes | Destination owner and optional folderId (JSON, or @path / @- to read a file or stdin). |

## Related docs \[#related-docs]

- [Files](/files)
- [Output formats](/cli/output)