Files

agentserve files is also spelled agentserve file.

Every command below also accepts the global options.

Delete several files at once

agentserve files batch-delete [options]

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 @).
`-y, --yes`	Yes	Confirm this operation.

POST /api/v2/files/copy

agentserve 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).

Create file

agentserve 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 70,000,000-character bound guards the JSON envelope; the decoded bytes must be at most 50 MiB, and a longer base64 payload is rejected with `413`. Use an upload session for anything larger.
`--encoding <value>`	No	Encoding of the content field. Accepted values: `utf-8`, `base64`.

Create a file folder at a path

agentserve files folders create <path>

Arguments

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

Delete folder

agentserve 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	Delete the folder and its descendants.
`-y, --yes`	Yes	Confirm this operation.

List folders

agentserve files folders list [options]

Also available as agentserve 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. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order. Accepted values: `name`, `createdAt`, `updatedAt`.
`--sort-order <value>`	No	Sort direction. 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.

Rename or move a file folder

agentserve files folders move <path> <destination>

Also available as agentserve 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

Restore an archived file folder

agentserve files folders restore <path>

Arguments

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

Delete file

agentserve files delete <fileId> [options]

Arguments

Argument	Required	Description
`fileId`	Yes	File identifier.

Options

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

Permanently delete a previous version of a file

agentserve 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.

Show the metadata of one version of a file

agentserve files versions describe <fileId> <version>

Arguments

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

List the recorded versions of a file

agentserve 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. Accepted values: `version`.
`--sort-order <value>`	No	Sort direction. 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.

Read the text content of one version of a file

agentserve 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.

Make a previous version of a file current again

agentserve 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.

Download the content of one version of a file

agentserve 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.

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

agentserve 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.

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

agentserve files share get <fileId>

Arguments

Argument	Required	Description
`fileId`	Yes	File identifier.

agentserve files share set <fileId> [options]

Enable or disable sharing for a file (OAuth login or personal API key required)

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 for a password-gated share. Kept when omitted; enabling `password` with neither a supplied nor a stored password is a 400.
`--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 @).

List files

agentserve 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. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order. Accepted values: `name`, `size`, `uploadedAt`, `updatedAt`.
`--sort-order <value>`	No	Sort direction. Accepted values: `asc`, `desc`.
`--limit <n>`	No	Maximum items to return (0 for everything). Defaults to `0`.

Move files into another folder

agentserve files move [options]

Also available as agentserve 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.

Read a file’s text content as JSON or YAML

agentserve files read <fileId> [options]

Arguments

Argument	Required	Description
`fileId`	Yes	File identifier.

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.

Rename a file

agentserve 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.

Restore an archived file

agentserve files restore <fileId>

Arguments

Argument	Required	Description
`fileId`	Yes	File identifier.

Search file content

agentserve 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. Accepted values: `exact`, `regex`.
`--max-results <value>`	No	Maximum matching lines to return.
`--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.

Unzip an archive into a new folder beside it

agentserve files unzip <fileId> [options]

Arguments

Argument	Required	Description
`fileId`	Yes	File identifier.

Options

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

Replace a file’s contents

agentserve 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 70,000,000-character bound guards the JSON envelope; the decoded bytes must be at most 50 MiB, and a longer base64 payload is rejected with `413`.
`--encoding <value>`	No	Content encoding. 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.

Upload a file to the workspace

agentserve 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.

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

agentserve 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.

List file resources and child folders together

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

Create a file directory at a path

agentserve files mkdir <path>

Arguments

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

Files

On this page