Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

storage

Store files inside your integrator.io account, with no external file provider to configure. Celigo Storage is a folder tree that the platform hosts for you. Exports and imports read and write files there instead of an SFTP, S3, or Google Drive connection. MCP servers serve stored files to MCP clients as resources.

This command group manages that tree: list, upload, download, organize, and delete files and folders.

REST API: File Storage

celigo storage <subcommand> [args] [flags]

Supports all global flags.

Subcommands

Subcommand
Purpose

list

List the items in one folder (the root by default), with optional MIME, sort, and date filters.

search <query>

Search items by name recursively across the whole tree.

get <ids...>

Get metadata for one or more items by ID — a batch get, up to 100 ids per call.

upload <localPath>

Upload a local file, choosing a single or multipart transfer by size.

download <id> [localPath]

Download a stored file to disk or stdout.

replace <id> <localPath>

Replace a file's contents in place, keeping its ID, name, parent, and references.

create-folder <name>

Create a folder.

set <id> key=value …

Edit a storage item's name and/or description.

move <ids...> --to <parentId>

Move up to 100 files or folders into another folder.

copy <id> --to <parentId>

Copy a file into another folder (files only).

merge <id> --to <destinationId>

Merge a folder's contents into another folder and remove the source (folders only).

delete <id>

Soft-delete an item to the recycle bin.

cancel-upload <id>

Abort an in-progress multipart upload.

celigo storage list

List the items in a single folder. With no --parent, list returns the root. With --parent <id>, it returns that folder's immediate children. Listings are one folder deep. Use search to look through the whole tree.

Signature

Arguments

None.

Flags

Flag
Type
Default
Description

--parent <id>

string

—

List the contents of this folder. Omit it for the root.

--mime <types...>

string (repeatable)

—

Keep only items whose MIME type matches one of the values; several types are OR-matched. Sent as one mimeType query parameter per value.

--sort <field>

string

—

Field to sort by, for example name, lastModified, or size. Sent as sort_by.

--order <dir>

string

—

Sort direction, asc or desc. Sent as sort_order.

--modified-gte <iso>

ISO 8601

—

Keep items whose lastModified is at or after this timestamp (inclusive). Sent as lastModified_gte.

--modified-lte <iso>

ISO 8601

—

Keep items whose lastModified is at or before this timestamp (inclusive). Sent as lastModified_lte.

Default table columns: _id, type, name, size, mimeType, status, lastModified.

Example

Corresponds to: GET /v1/storage/items — with _parentId and the filter parameters above as query parameters. The CLI follows the response's Link: rel="next" cursor and returns the accumulated pages as one list.

celigo storage search

Search items by name across the entire tree, regardless of which folder holds them. search accepts the same MIME, sort, and date filters as list.

Signature

Arguments

Argument
Type
Required
Description

<query>

string

Yes

Text to match against item names. Matching is recursive from the root.

Flags

Flag
Type
Default
Description

--mime <types...>

string (repeatable)

—

Keep only items whose MIME type matches one of the values; several types are OR-matched. Sent as one mimeType query parameter per value.

--sort <field>

string

—

Field to sort by, for example name, lastModified, or size. Sent as sort_by.

--order <dir>

string

—

Sort direction, asc or desc. Sent as sort_order.

--modified-gte <iso>

ISO 8601

—

Keep items whose lastModified is at or after this timestamp (inclusive). Sent as lastModified_gte.

--modified-lte <iso>

ISO 8601

—

Keep items whose lastModified is at or before this timestamp (inclusive). Sent as lastModified_lte.

Default table columns: _id, type, name, size, mimeType, status, lastModified.

Example

Corresponds to: GET /v1/storage/items?search=<query> — the same collection endpoint as list, with a search query parameter instead of _parentId.

celigo storage get

Get metadata for one or more items by ID — a batch get, up to 100 ids per call. Returns one entry per id, in request order. All metadata fields are requested by default; narrow the set with --fields. The path field is a breadcrumb built from the item's ancestor folder names (e.g. /invoices/2026/inv-001.pdf).

An unknown id fails the whole request (422) unless --no-fail-fast, which reports unknown ids inline as {"_id", "notFound": true} entries alongside the found items.

File ids only for now: despite the endpoint's item vocabulary, a folder id is rejected as not-found — folder metadata comes from list/search instead.

Signature

Arguments

Argument
Type
Required
Description

<ids...>

string (variadic)

Yes

One or more storage file ids (up to 100).

Flags

Flag
Type
Default
Description

--fields <fields>

string

all of them

Comma-separated fields to return per item (_id always rides along). Allowed: name, description, size, mimeType, type, status, _parentId, __ancestorIds, path.

--no-fail-fast

boolean

false

Report unknown ids inline instead of failing the whole request.

Example

Corresponds to: POST /v1/storage/items/batch — a pure read; the batch endpoint is on the CLI's read-only-POST allowlist, so it works in read mode.

celigo storage upload

Upload a local file. The CLI reads the file's size and asks the API to start an upload. It then streams the bytes to the presigned URLs it gets back. Files up to 5 MiB use a single PUT; larger files use a multipart transfer. The MIME type is derived from the file extension. Unrecognized extensions become application/octet-stream.

Signature

Arguments

Argument
Type
Required
Description

<localPath>

string

Yes

Path to a local file. It must exist and be a regular file.

Flags

Flag
Type
Default
Description

--parent <id>

string

—

Destination folder. Omit it to upload into the root.

--name <name>

string

the local filename

Name to store the file as.

Example

Corresponds to: POST /v1/storage/files/initiateUpload, followed by the file bytes going straight to the presigned storage URL(s) returned in the response. That second leg is an out-of-band transfer, not a Celigo API call — your API token is never sent with it.

celigo storage download

Download a stored file by ID. The optional path controls where the bytes go:

[localPath]

Result

omitted

Writes to the current directory under the stored name.

an existing directory

Writes into that directory under the stored name.

a file path

Writes to exactly that path.

-

Streams the bytes to stdout.

Signature

Arguments

Argument
Type
Required
Description

<id>

string

Yes

Storage item ID of the file.

[localPath]

string

No

Destination: a directory, an explicit file path, or - for stdout. Defaults to the stored filename in the current directory.

Flags

Uses global flags only.

Example

Corresponds to: GET /v1/storage/files/{_id}/download, which returns a downloadUrl; the CLI then streams the bytes from that presigned URL (an out-of-band transfer, not a Celigo API call).

celigo storage replace

Swap a file's contents for the contents of a local file. The item keeps its ID, name, parent folder, and every inbound reference. Exports, imports, and MCP server resources that point at this file keep working and read the new bytes on their next run. Use replace for a recurring drop of the same logical file. Use upload when you want a new item.

⚠️ replace overwrites the stored contents. The previous bytes are gone — no earlier version is kept. Download the current contents first if you might need them.

Signature

Arguments

Argument
Type
Required
Description

<id>

string

Yes

Storage item ID of the file to replace.

<localPath>

string

Yes

Local file whose contents become the item's new contents.

Flags

Uses global flags only.

Example

Corresponds to: PATCH /v1/storage/items/{_id}/replace, followed by the same single or multipart transfer to the presigned URL(s) that upload uses. The stored name is untouched — the CLI does not send one, and the API ignores a name if it receives one.

celigo storage create-folder

Create a folder, in the root or inside another folder.

Signature

Arguments

Argument
Type
Required
Description

<name>

string

Yes

Folder name.

Flags

Flag
Type
Default
Description

--parent <id>

string

—

Parent folder. Omit it to create the folder in the root.

Example

Corresponds to: POST /v1/storage/items with type: "folder", the name, and _parentId when --parent is given.

celigo storage set

Rename a file or folder, or change its description. These are the only two editable fields on a storage item.

set behaves differently here than in other command groups. It sends one partial PUT, and the storage endpoint merges only the fields you name. There is no GET-then-PUT round trip, so fields you omit are never cleared.

Signature

Arguments

Argument
Type
Required
Description

<id>

string

Yes

Storage item ID (file or folder).

<key=value>

string

Yes (≥1)

Field assignments. Only name and description are accepted; the API rejects anything else.

Flags

Uses global flags only.

Example

Corresponds to: PUT /v1/storage/items/{_id} with a partial body containing only the fields you assigned.

celigo storage move

Move one or more items — up to 100 — into a different folder. Pass the literal root to move items to the top level. Folder moves cascade asynchronously.

A single id goes through the per-item move endpoint, exactly as before celigo-cli 2026.8.7. Several ids — or --name — route to the bulk endpoint, which validates the destination once up front and then moves each item best-effort: a mixed batch returns per-id success/error results. --name renames the item as it lands (exactly one id), resolving a destination name collision without a second call.

Signature

Arguments

Argument
Type
Required
Description

<ids...>

string (variadic)

Yes

One or more storage item IDs (files or folders, up to 100).

Flags

Flag
Type
Default
Description

--to <parentId>

string

—

Required. Destination folder ID, or the literal root for the top level.

--name <name>

string

—

New name applied in the same write as the move. Single id only.

Example

Corresponds to: PATCH /v1/storage/items/{_id}/move for a single id with no --name (destination as _parentId; --to root is sent as null), or POST /v1/storage/items/move for several ids or --name.

celigo storage copy

Copy a file into another folder, optionally under a new name. Files only — folders cannot be copied.

Signature

Arguments

Argument
Type
Required
Description

<id>

string

Yes

Storage item ID of the file to copy.

Flags

Flag
Type
Default
Description

--to <parentId>

string

—

Required. Destination folder ID, or the literal root for the top level.

--name <name>

string

the source name

Name for the copy.

Example

Corresponds to: POST /v1/storage/items/{_id}/copy with the destination as _parentId (--to root is sent as null) and the optional name.

celigo storage merge

Move one folder's contents into another folder, then remove the source folder. Folders only. To relocate a single file, use move.

The API returns 202 Accepted and transfers the items in the background. The destination fills in over the seconds that follow, not instantly. Merging a soft-deleted folder restores its contents into the destination. That is one way to recover a deleted folder's files into a folder you choose.

⚠️ merge removes the source folder. Once the background job finishes, the source folder no longer exists — its contents live under the destination. Confirm the destination ID before running it.

Signature

Arguments

Argument
Type
Required
Description

<id>

string

Yes

Source folder ID. Must be a folder.

Flags

Flag
Type
Default
Description

--to <destinationId>

string

—

Required. Destination folder ID. Must be an existing folder.

Example

Corresponds to: POST /v1/storage/items/{_id}/merge with the destination as _destinationId.

celigo storage delete

Soft-delete a file or folder. The item moves to the Recycle Bin instead of being destroyed. Deleting a folder cascades to everything inside it. The command prompts for confirmation unless you pass -y.

⚠️ Deleting a folder deletes its whole subtree. Every descendant file and folder is soft-deleted with it, and the cascade runs in the background. Exports, imports, and MCP server resources that reference a deleted file begin failing. Check what points at the item before you delete it.

Signature

Arguments

Argument
Type
Required
Description

<id>

string

Yes

Storage item ID (file or folder).

Flags

Flag
Type
Default
Description

-y, --yes

boolean

false

Skip the confirmation prompt.

Example

Corresponds to: DELETE /v1/storage/items/{_id}. To restore the item, use recycle-bin.

celigo storage cancel-upload

Abort an in-progress multipart upload, discarding any uploaded parts. Use it to clean up an item stuck in uploading after an interrupted upload.

Signature

Arguments

Argument
Type
Required
Description

<id>

string

Yes

Storage item ID of the stuck upload.

Example

Corresponds to: POST /v1/storage/files/{_id}/cancel

Gotchas

  • Celigo Storage requires a separate account entitlement. Without it, writes fail with STORAGE_NOT_ENTITLED. Reads behave differently: storage list returns an empty list rather than an error. An empty root is therefore not proof that the tree is empty. Check your subscription if every listing comes back empty.

  • copy handles files only; merge handles folders only. move is the one verb that accepts both. Folders cannot be copied. To duplicate a folder, create the destination and copy its files in one at a time. Use merge only when you are willing to lose the source folder.

  • --to root reaches the top level. move and copy accept a folder ID or the literal string root. The CLI sends root as a null parent. merge has no equivalent — its destination must be an existing folder.

  • merge runs asynchronously. The command returns as soon as the API accepts the job. A list of the destination immediately afterward can look incomplete. Re-list after a few seconds before concluding the merge failed. Folder move and delete cascade in the background the same way.

  • A multi-id move is best-effort. The bulk endpoint validates the destination once up front, then moves each item independently — a mixed batch returns per-id success/error results instead of failing whole. Check the per-id results before assuming everything landed.

  • storage get reads files only. A folder id is rejected as not-found despite the endpoint's item vocabulary; folder metadata comes from list/search.

  • set accepts only name and description. Every other field on a storage item is server-owned, and the API rejects attempts to change it. mimeType is derived from the name at upload time and is not settable. To correct a wrong MIME type, replace the file using a name with the correct extension.

  • delete is reversible; recycle-bin purge is not. Deleted items stay in the Recycle Bin for the retention window. celigo recycle-bin restore <id> brings a file or folder back, and a restored folder brings its contents with it. celigo recycle-bin purge <id> removes the item permanently. Both take the ID alone — the Recycle Bin resolves the resource type itself.

  • Storage names reject several characters. [ and ] are invalid in file and folder names. So are the other characters that are illegal in S3 keys, SFTP paths, and Windows filenames. An invalid name fails with an error instead of being sanitized. Strip these characters from generated names before uploading.

  • Uploads larger than 5 MiB switch to multipart automatically. At or below 5 MiB the CLI sends one presigned PUT. Above it, the file is split into 5 MiB parts and finalized in one completion call. Very large files use a larger part size to keep the part count within the transfer limit. Either way the bytes stream from disk, so memory use stays flat for multi-gigabyte files.

  • The listing index is eventually consistent. A newly uploaded file can take a moment to appear in list. search uses a separate index and can lag by minutes on a busy account. download <id> works immediately. Use the ID that upload returns rather than waiting for the file to appear in a listing.

  • download overwrites the target path without prompting. There is no --force flag and no confirmation. When scripting, download into a fresh directory, or rely on the default stored-name behavior for a predictable filename.

  • Storage listings are never field-projected. list and search always return complete item documents. The field projection that trims other list commands does not apply here.

  • Write verbs require the right permission mode. merge and delete require full mode. set does too in practice: operate mode restricts set to an allowlist of operational fields, and neither name nor description is on it. upload, replace, create-folder, move, copy, and cancel-upload run in operate mode. Every read-only verb works in read mode — including get, whose batch POST is on the read-only-POST allowlist. See Profiles & regions.

Related

  • recycle-bin — restore or permanently purge items that storage delete removed.

  • exports — a file export can read from a Celigo Storage folder instead of an external file provider.

  • imports — a file import can write its output into a Celigo Storage folder.

  • mcp-servers — serve stored files to MCP clients as resources, referenced by file ID. Folder IDs are rejected.

Previousstate
Nextsubscriptions

Last updated

Was this helpful?