Skip to content
Try for free
On this page

Commands

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.

Browse and inspect

List file resources and child folders together

Code
sim files ls [path] [options]

Arguments

ArgumentRequiredDescription
pathNoFolder path to list; defaults to the root folder

Options

OptionRequiredDescription
--search <text>NoFilter folders and resources by name.
--limit <n>NoMaximum combined items to return (0 for everything). Defaults to 0.

API request and response schemas: listFiles, listFileFolders.

List files

Code
sim files list [options]

Options

OptionRequiredDescription
--folder <value>NoFolder path as shown in the app; the leading / is optional.
--recursiveNoInclude subfolders in the folder filter. Defaults to true when searching and false otherwise. Ignored without a folder filter.
--no-recursiveNoSend --recursive as false.
--scope <value>NoWhich 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>NoCase-insensitive substring match against the file name.
--sort-by <value>NoField 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>NoSort direction. Defaults to "asc". Accepted values: asc, desc.
--limit <n>NoMaximum items to return (0 for everything). Defaults to 0.

API request and response schemas: listFiles.

Search file content

Code
sim files search [options]

Options

OptionRequiredDescription
--query <value>YesRegular expression, or exact text when mode is exact.
--mode <value>NoHow query is read. Defaults to "regex". Accepted values: exact, regex.
--max-results <value>NoMaximum matching lines to return. Defaults to 50.
--folder <value...>NoFolders 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-subfoldersNoWhether each folder scope includes nested folders; on by default.
--no-include-subfoldersNoSend --include-subfolders as false.

API request and response schemas: searchFileContent.

Show file metadata and sharing status

Code
sim files describe <fileId> [options]

Arguments

ArgumentRequiredDescription
fileIdYesFile 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

OptionRequiredDescription
--scope <value>NoWhich 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

Code
sim files upload <path> [options]

Arguments

ArgumentRequiredDescription
pathYesLocal file to upload

Options

OptionRequiredDescription
--folder <path>NoFolder path as shown in the app; defaults to the root folder.
--name <name>NoStore it under a different name.

API request and response schemas: createFileUpload, createFileUploadPartUrls, completeFileUpload, abortFileUpload.

Create file

Code
sim files create [options]

Options

OptionRequiredDescription
--name <value>YesFile name, including its extension. Path separators and dot segments are rejected.
--content-type <value>NoMIME type. When omitted, it is inferred from the file extension.
--folder <value>NoFolder path as shown in the app; the leading / is optional.
--content <value>NoInitial 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>NoEncoding 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

Code
sim files get <fileId> [options]

Arguments

ArgumentRequiredDescription
fileIdYesFile whose content to read: its id, or its files/<folder>/<name> VFS path

Options

OptionRequiredDescription
-o, --output-file <path>NoWrite content to a file instead of stdout.
--forceNoOverwrite --output-file if it already exists.

API request and response schemas: downloadFile.

Read a file’s text content as JSON or YAML

Code
sim files read <fileId> [options]

Arguments

ArgumentRequiredDescription
fileIdYesFile identifier, or the file’s VFS path: files/<folder>/<name>, or uploads/<name> for a Chat upload.

Options

OptionRequiredDescription
--max-bytes <value>NoOptional ceiling on the source bytes fed to the parser, lowering but never raising the server limit.
--offset <value>NoFirst line to return, 1-based; 0 also starts at the first line. Absent starts at the first line.
--limit <value>NoHow 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

Code
sim files edit <fileId> [options]

Arguments

ArgumentRequiredDescription
fileIdYesFile identifier.

Options

OptionRequiredDescription
--edit <json|@file>YesOne 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>NoRevision 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

Code
sim files set-content <fileId> [options]

Arguments

ArgumentRequiredDescription
fileIdYesFile identifier.

Options

OptionRequiredDescription
--content <value>YesComplete 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>NoContent encoding. Defaults to "utf-8". Accepted values: utf-8, base64.
--expected-revision <value>NoRevision 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

Code
sim files rename <fileId> [options]

Arguments

ArgumentRequiredDescription
fileIdYesFile 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

OptionRequiredDescription
--name <value>YesNew file name, including its extension.

API request and response schemas: renameFile.

Move files into another folder

Code
sim files move [options]

Also available as sim files mv.

Options

OptionRequiredDescription
--file-ids <value...>YesFile identifiers to update. (space-separated, or @path / @- with one value per line; @@value for a literal leading @).
--to <value>NoDestination 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.

Code
sim files unzip <fileId> [options]

Arguments

ArgumentRequiredDescription
fileIdYesFile identifier.

Options

OptionRequiredDescription
-y, --yesYesConfirm this operation.

API request and response schemas: unzipFile.

Sharing

Show a file’s share settings

Code
sim files share get <fileId>

Arguments

ArgumentRequiredDescription
fileIdYesFile identifier.

API request and response schemas: getFileShare.

Enable or disable sharing for a file

OAuth login or personal API key required.

Code
sim files share set <fileId> [options]

Arguments

ArgumentRequiredDescription
fileIdYesFile identifier.

Options

OptionRequiredDescription
--is-active <true|false>YesWhether 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>NoHow 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>NoPassword 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...>NoAllowed 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

Code
sim files versions list <fileId> [options]

Arguments

ArgumentRequiredDescription
fileIdYesFile identifier.

Options

OptionRequiredDescription
--sort-by <value>NoField used to sort the result. Defaults to "version". Accepted values: version.
--sort-order <value>NoSort direction. Defaults to "desc". Accepted values: asc, desc.
--limit <n>NoMaximum items to return (0 for everything). Defaults to 100.
--cursor <value>NoContinue from nextCursor returned by a previous result.

API request and response schemas: listFileVersions.

Show the metadata of one version of a file

Code
sim files versions describe <fileId> <version>

Arguments

ArgumentRequiredDescription
fileIdYesFile identifier.
versionYesVersion number.

API request and response schemas: getFileVersion.

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

Code
sim files versions read <fileId> <version> [options]

Arguments

ArgumentRequiredDescription
fileIdYesFile identifier.
versionYesVersion number.

Options

OptionRequiredDescription
--max-bytes <value>NoOptional ceiling on the source bytes fed to the parser, lowering but never raising the server limit.
--offset <value>NoFirst line to return, 1-based; 0 also starts at the first line. Absent starts at the first line.
--limit <value>NoHow 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

Code
sim files versions download <fileId> <version> [options]

Arguments

ArgumentRequiredDescription
fileIdYesFile identifier.
versionYesVersion number.

Options

OptionRequiredDescription
-o, --output-file <path>NoWrite content to a file instead of stdout.
--forceNoOverwrite --output-file if it already exists.

API request and response schemas: downloadFileVersion.

Make a previous version of a file current again

Code
sim files versions revert <fileId> <version> [options]

Arguments

ArgumentRequiredDescription
fileIdYesFile identifier.
versionYesVersion number.

Options

OptionRequiredDescription
--expected-current-version <value>NoRevert 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>NoRevert 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.

Code
sim files versions delete <fileId> <version> [options]

Arguments

ArgumentRequiredDescription
fileIdYesFile identifier.
versionYesVersion number.

Options

OptionRequiredDescription
-y, --yesYesConfirm this operation.

API request and response schemas: deleteFileVersion.

Archive and restore

Delete file

This archives the file.

Code
sim files delete <fileId> [options]

Arguments

ArgumentRequiredDescription
fileIdYesFile 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

OptionRequiredDescription
-y, --yesYesConfirm this operation.

API request and response schemas: deleteFile.

Delete several files at once

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

Code
sim files batch-delete [file-ids...] [options]

Arguments

ArgumentRequiredDescription
file-ids...NoFiles 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

OptionRequiredDescription
--file-ids <value...>NoFiles 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, --yesYesConfirm this operation.

API request and response schemas: bulkDeleteFiles.

Restore an archived file

Code
sim files restore <fileId>

Arguments

ArgumentRequiredDescription
fileIdYesFile identifier.

API request and response schemas: restoreFile.

Folders

List folders

Code
sim files folders list [options]

Also available as sim files folders ls.

Options

OptionRequiredDescription
--parent <value>NoDirect parent folder path.
--search <value>NoCase-insensitive substring match against the folder name.
--sort-by <value>NoField 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>NoSort direction. Defaults to "asc". Accepted values: asc, desc.
--scope <value>NoWhich 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>NoWhether 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>NoDeepest level below parentPath to include when recursive is true.

API request and response schemas: listFileFolders.

Create a file folder at a path

Code
sim files folders create <path>

Arguments

ArgumentRequiredDescription
pathYesFolder 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.

Code
sim files folders delete <path> [options]

Arguments

ArgumentRequiredDescription
pathYesFolder path as shown in the app; the leading / is optional

Options

OptionRequiredDescription
--recursiveNoArchive the folder and its descendants. Defaults to "false".
-y, --yesYesConfirm this operation.

API request and response schemas: deleteFileFolder.

Restore an archived file folder

Code
sim files folders restore <path>

Arguments

ArgumentRequiredDescription
pathYesFolder path as shown in the app; the leading / is optional

API request and response schemas: restoreFileFolder.

Rename or move a file folder

Code
sim files folders move <path> <destination>

Also available as sim files folders mv.

Arguments

ArgumentRequiredDescription
pathYesFolder path as shown in the app; the leading / is optional
destinationYesFolder path as shown in the app; the leading / is optional

API request and response schemas: relocateFileFolder.

Create a file directory at a path

Code
sim files mkdir <path>

Arguments

ArgumentRequiredDescription
pathYesFolder 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.

Code
sim files copy [options]

Options

OptionRequiredDescription
--source <json|@file>YesSource owner and selected fileIds or folderIds (JSON, or @path / @- to read a file or stdin).
--destination <json|@file>YesDestination owner and optional folderId (JSON, or @path / @- to read a file or stdin).

Related docs

Was this helpful?
Suggest an edit