CesiumCloud — Node.js CLI and SDK

Release 0.2.41 · Node.js 22+ · Windows, macOS and Linux

Manage cloud files and folders from the terminal or from Node.js. Uploads, downloads, navigation, listing, searching, moving, renaming, deletion and optional locally encrypted files are supported.

Web app: https://cloud.cesiummc.space/app/ · npm: https://www.npmjs.com/package/cesiumcloud · Complete reference

Install and sign in

npm install -g [email protected]
cesiumcloud --version
cesiumcloud authenticate
cesiumcloud whoami

Follow the browser/device-authorization instructions. A locally saved credential is used for subsequent commands. You do not need to paste a token into terminal commands.

On Windows PowerShell or CMD, use npm.cmd and cesiumcloud.cmd if shell command resolution requires them. Always quote complete Windows paths containing spaces, special characters or parentheses.

npm.cmd install -g [email protected]
cesiumcloud.cmd authenticate
cesiumcloud.cmd upload "E:\Downloads\My project (1).zip"

cesiumcloud upgrade (or update) installs the current release from the official npm registry. cesiumcloud logout deletes the saved local credential; revoke devices separately through your CesiumCloud account.

Command reference

You can run cesiumcloud help COMMAND or cesiumcloud COMMAND --help for command-specific help. [and] and [to] are literal separators, not filenames. For multi-source commands, quote each path separately.

Upload files and directories

cesiumcloud upload "./backup.zip"
cesiumcloud upload "./Projects"
cesiumcloud upload "./backup.zip" --replace
cesiumcloud upload "./a.zip" [and] "./b.zip" -simultaneous 2
cesiumcloud upload "./My Folder" -simultaneous 20

Single-file uploads use the standard configuration described below. When uploading a directory, its nested paths and empty folders are preserved. Multiple sources and directory uploads run independent file transfers, with up to 40 active file uploads by default for directories; -simultaneous N or --simultaneous N controls concurrency (accepted N: 1–64; active upload limit 40). Uploads are admitted as capacity becomes available. An existing cloud path requires --replace.

Download files, directories and the whole account

cesiumcloud download "archive.zip"
cesiumcloud download "archive.zip" --location "./Restored"
cesiumcloud download "photos" --location "./Restored"
cesiumcloud download "first.zip" [and] "second.zip" --location "./Restored" -simultaneous 2
cesiumcloud download --all "./RestoredAccount" -simultaneous 8

Without --location, named downloads use the OS Downloads directory, not necessarily the current terminal directory. Existing local filenames are preserved by choosing a numbered alternative. When downloading a folder, the folder is created beneath the chosen destination with its nested structure and empty folders. --all restores the account hierarchy below the selected local directory. Download concurrency is 1–64 (default: 1).

Browse, organize and delete

cesiumcloud dir /
cesiumcloud dir "photos"
cesiumcloud dir ..
cesiumcloud list
cesiumcloud list -a
cesiumcloud list -n 20 -sort name
cesiumcloud list -next 15
cesiumcloud list -sort datecreated -long
cesiumcloud search ext:png
cesiumcloud search "holiday" [and] "2026"
cesiumcloud rename "old.txt" "new.txt"
cesiumcloud rename "old.txt" "newname" -ne
cesiumcloud move "a.txt" [and] "b.txt" [to] "archive"
cesiumcloud delete "archive/a.txt"

dir with no arguments shows the current cloud directory; dir / returns to account root. list defaults to the first 15 files sorted by size; -a lists recursively, -n N (or N / -N) controls count, -next N advances the saved cursor, -sort takes size, name, datecreated, lastmodified or reset; -long shows metadata. search uses case-insensitive path matching; ext:png matches extension. rename keeps an existing file's extension when a new name has no extension unless -ne is provided. delete is permanent.

Cancelling transfers

Since 0.2.41, Ctrl+C reports permanent cancellation as complete only after the remote upload session and its reservation have been deleted; it reports pending cleanup explicitly if deletion cannot be confirmed promptly after handing remote deletion and queue cleanup to a detached process. The message means cleanup is in progress, not that server deletion has already been confirmed. Check cesiumcloud uploads if needed.

• During a Node.js CLI transfer, Ctrl+C requests cancellation. v0.2.29 adds Windows Ctrl+C and Ctrl+Break console handling; normal Unix SIGINT behavior remains supported. If the terminal treats Ctrl+C as copy while text is selected, clear the selection.
• From a second terminal on the same computer, use cesiumcloud upload cancel or cesiumcloud download cancel. These commands also work when console interrupt keys are intercepted. They affect only jobs in the same CesiumCloud CLI configuration, not jobs on another device or the website.
• cesiumcloud cancel-upload UPLOAD_ID can cancel a specific unfinished server upload. Use cesiumcloud uploads to inspect entries requiring cleanup.
• A cancelled or failed upload is not kept for later resumption. Its unfinished server data is removed; already completed cloud files are preserved. Cancellation may take longer if the server is confirming cleanup. A forcibly terminated process may require automatic recovery and cleanup.
• Cancelled downloads remove incomplete temporary local files; already completed downloads remain. No remote file is deleted by download cancellation.

Upload settings

Default for a single file (Node.js): 99,876,864-byte chunks (the largest 256 KiB-aligned size under 100,000,000 bytes), 1 MiB HTTP stream blocks and one-chunk read-ahead. No environment variables are needed. These defaults were selected from real transfer measurements; throughput depends on your connection and storage capacity.

Read-ahead may use about one additional 100 MB chunk of memory. Concurrent folder uploads use smaller per-file chunks to control memory usage.

PowerShell:

$env:CESIUMCLOUD_UPLOAD_PREFETCH = "0"
cesiumcloud.cmd upload "E:\Backups\archive.zip"
Remove-Item Env:\CESIUMCLOUD_UPLOAD_PREFETCH

Bash:

CESIUMCLOUD_UPLOAD_PREFETCH=0 cesiumcloud upload "./archive.zip"

Folder/batch transfers use a separate file-upload path and are not equivalent to a single large-file transfer.

JavaScript SDK

The package exports IsolatedTransferClient for file management and CesiumCloudClient for high-level device authorization and CLI-backed operations. In Node.js 22+:

const { IsolatedTransferClient } = require("cesiumcloud");
const client = new IsolatedTransferClient(process.env.CESIUMCLOUD_API_KEY);
async function example() {
  await client.uploadFile("./notes.txt", "docs/notes.txt");
  const files = await client.allFiles();
  const doc = files.find(file => file.path === "docs/notes.txt");
  if (doc) await client.download(doc.id, "./notes-restored.txt");
}
example().catch(console.error);

An SDK operation requires a valid authorized token. The lower-level client supports uploadFile, uploadPath, download, downloadPath, list, allFiles, byPath, delete, rename, renameFolder, mkdir, rmdir, directoryExists, pendingUploads, cancelUpload and more; see the SDK reference. SDK downloads reject an existing destination by default unless you explicitly enable overwrite, unlike CLI downloads that choose numbered filenames.

Optional end-to-end encryption

cesiumcloud e2ee keygen
cesiumcloud e2ee encrypt "./notes.txt" --location "./Encrypted"
cesiumcloud e2ee decrypt "./Encrypted/notes.txt.ccenc" --location "./Restored"
cesiumcloud e2ee upload "./notes.txt"
cesiumcloud e2ee download "notes.txt.ccenc" --location "./Restored"
cesiumcloud e2ee migrate "old.txt"

keygen creates a locally stored recovery key. Back it up offline and never disclose it. Normal upload remains unencrypted. The encrypted .ccenc format protects contents, not paths, filenames, sizes or activity metadata. e2ee migrate creates and verifies an encrypted copy while retaining the original by default; removal of the original requires both --purge-original and --i-backed-up-key. Never set the purge flags without retaining a usable recovery key.

Troubleshooting and compatibility

For help use cesiumcloud --help and cesiumcloud e2ee help. For command examples, environment variables, and historical changes, consult the documentation included with the source release.

Safety: CLI delete uses recoverable 48-hour Trash; explicit SDK deletion is permanent, and upload replacement can change existing content. Preserve independent backups of important files and encryption keys.

Windows version and package upgrades

Use where cesiumcloud to check which executable Windows starts. Python's Scripts executable may precede the npm CLI on PATH. Use cesiumcloud.cmd version for the npm global client or python -m cesiumcloud version for Python. The upgrade and update commands update both package types when both are installed. For npm global installation use npm install -g cesiumcloud; without -g npm installs into the current project.

Uploads are admitted through a queue before bytes are transferred. The service enforces admission to prevent skipping the queue by making direct requests. Upload chunk sizes are capped at 100 MB.

Folder deletion in 0.2.41

Use the delete command with a quoted cloud folder path. It moves that directory and all its contents into the 48-hour recoverable Trash, including empty folders; it never calls permanent deletion. A trailing Windows backslash is supported.