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

import { CommandTable } from '@/components/ui/command-table'

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.

Browse and inspect

List file resources and child folders together

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, listFileFolders.

List files

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.

Search file content

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.

Show file metadata and sharing status

sim files describe <fileId> [options]

Arguments

Argument	Required	Description
fileId	Yes	File identifier.

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.

Upload, create, and read

Upload a file to the workspace

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, createFileUploadPartUrls, completeFileUpload, abortFileUpload.

Create file

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.

Download a file’s content to stdout or a local file

sim files get <fileId> [options]

Arguments

Argument	Required	Description
fileId	Yes	File whose content to read

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.

Read a file’s text content as JSON or YAML

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.

Edit and organize

Apply one exact or anchor-based edit to a text file

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.

Replace a file’s contents

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.

Rename a file

sim files rename <fileId> [options]

Arguments

Argument	Required	Description
fileId	Yes	File identifier.

Options

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

API request and response schemas: renameFile.

Move files into another folder

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.

Unzip an archive into a new folder beside it

This writes every file in the archive into the workspace.

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.

Sharing

Show a file’s share settings

sim files share get <fileId>

Arguments

Argument	Required	Description
fileId	Yes	File identifier.

API request and response schemas: getFileShare.

Enable or disable sharing for a file

OAuth login or personal API key required.

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.

Versions

List the recorded versions of a file

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.

Show the metadata of one version of a file

sim files versions describe <fileId> <version>

Arguments

Argument	Required	Description
fileId	Yes	File identifier.
version	Yes	Version number.

API request and response schemas: getFileVersion.

Read the text content of one version of a file as JSON or YAML

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.

Download the content of one version of a file

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.

Make a previous version of a file current again

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.

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.

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.

Archive and restore

Delete file

This archives the file.

sim files delete <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: deleteFile.

Delete several files at once

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

sim files batch-delete [options]

Options

Option	Required	Description
--file-ids <value...>	Yes	File identifiers to delete. (space-separated, or @path / @- with one value per line; @@value for a literal leading @).
-y, --yes	Yes	Confirm this operation.

API request and response schemas: bulkDeleteFiles.

Restore an archived file

sim files restore <fileId>

Arguments

Argument	Required	Description
fileId	Yes	File identifier.

API request and response schemas: restoreFile.

Folders

List folders

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.

Create a file folder at a path

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.

Delete folder

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

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.

Restore an archived file folder

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.

Rename or move a file folder

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.

Create a file directory at a path

sim files mkdir <path>

Arguments

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

API request and response schemas: createFileFolder.

Other commands

Copy file items

OAuth login or personal API key required.

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

• Files
• Output formats