Storage API

Quick start — CLI 0.2.9

The current CesiumCloud command-line client is 0.2.9 on npm and PyPI. It supports upload, download, search, file management, transfer progress, and cancellation. Authorize the CLI once with your CesiumCloud account before using file commands.

npm install --global [email protected]
cesiumcloud --version
cesiumcloud authenticate
cesiumcloud upload "C:\Users\you\Documents\notes.txt"
cesiumcloud list -a
cesiumcloud download "notes.txt" --location "C:\Users\you\Downloads"

The npm CLI requires Node.js 22 or newer. Run cesiumcloud --help or cesiumcloud help upload to see the available options. The npm and Python releases share the same core command syntax.

Python SDK and CLI

Install CesiumCloud 0.2.9 with Python 3.10 or newer. On systems that manage Python packages for you, use a virtual environment rather than installing into system Python.

python -m pip install --upgrade cesiumcloud==0.2.9
python -m cesiumcloud --version
python -m cesiumcloud authenticate
python -m cesiumcloud upload "./My Documents"
python -m cesiumcloud download --all "./CesiumCloud Restore"

You can use the same commands with the installed cesiumcloud executable. The Python package also provides programmatic account-scoped file operations.

Linux installation

For Ubuntu and Debian, install Python and create an isolated virtual environment. This works without Node.js.

sudo apt-get update
sudo apt-get install -y python3 python3-venv
python3 -m venv "$HOME/.local/share/cesiumcloud/venv"
"$HOME/.local/share/cesiumcloud/venv/bin/python" -m pip install --upgrade cesiumcloud==0.2.9
"$HOME/.local/share/cesiumcloud/venv/bin/cesiumcloud" authenticate

Windows users can run the command in PowerShell; macOS users can install either the Python CLI or the npm CLI. Always quote paths containing spaces or parentheses.

Account authentication

Run cesiumcloud authenticate and approve the displayed device authorization using your CesiumCloud account. Use cesiumcloud whoami to check the active account and cesiumcloud logout to remove the locally saved authorization. Logging out of one device does not delete your cloud files.

cesiumcloud authenticate
cesiumcloud whoami
cesiumcloud logout

Keep account credentials private. Do not paste authentication codes or saved credentials into public issues, support messages, or shared documents.

Paths and folders

Cloud paths identify files and directories within your own account. A path such as root/photos/holiday.jpg refers to the file in your cloud storage; it is not a local computer path. Use cesiumcloud dir to browse directories and cesiumcloud list -a to see files across your account.

File names and directory names are preserved where supported. If a command reports an ambiguous path, use a more specific path rather than guessing which file it will select.

Complete CLI command reference — 0.2.9

cesiumcloud authenticate
cesiumcloud whoami
cesiumcloud logout

cesiumcloud upload SOURCE [and SOURCE...] [--replace] [-simultaneous N]
cesiumcloud upload cancel
cesiumcloud cancel-upload UPLOAD_ID

cesiumcloud download CLOUDPATH [and CLOUDPATH...] [--location DIR] [-simultaneous N]
cesiumcloud download --all LOCALDIR [-simultaneous N]
cesiumcloud download cancel

cesiumcloud list [options] [CLOUDDIR]
cesiumcloud search TERM
cesiumcloud dir [CLOUDDIR|..|-|/]
cesiumcloud rename OLD NEW
cesiumcloud move SOURCE [and SOURCE...] [to] DESTINATION
cesiumcloud delete CLOUDPATH [and CLOUDPATH...]

cesiumcloud e2ee help
cesiumcloud help COMMAND

The literal separators [and] and [to] allow multiple source paths and a move destination. Use quotes around each path when necessary.

Upload files and folders

Upload a single file or a directory recursively. Multiple files may upload concurrently, and the CLI reports progress and errors. To replace an existing file with the same cloud path, use --replace.

cesiumcloud upload "./photos"
cesiumcloud upload "./notes.txt" --replace
cesiumcloud upload "./photos" -simultaneous 20

Uploads are subject to your account's available storage and service availability. A completed file stays available even if a later file in the same operation fails or is cancelled.

Multiple sources and concurrency

Supply several local files or folders in a single command by separating them with the literal [and] argument. Set -simultaneous N to specify a concurrency preference; the current CLI supports up to 40 active uploads.

cesiumcloud upload "./Folder A" [and] "./Folder B" -simultaneous 20
cesiumcloud upload "./first.txt" [and] "./second.txt"

The number of simultaneous transfers is a limit, not a guaranteed upload speed. The server may temporarily ask clients to wait or retry.

Download named files

Download one or more named cloud files. Without --location, files are saved to your operating system's Downloads folder. If an output filename already exists, the CLI uses an available numbered name rather than silently overwriting it.

cesiumcloud download "root/photos/holiday.jpg"
cesiumcloud download "first.txt" [and] "second.txt" --location "./Restored"
cesiumcloud download "root/videos/clip.mp4" --location "E:\Videos"

Quote the entire cloud path when it contains spaces or parentheses.

Restore all files

Use download --all to restore every file in your account to a chosen local directory. This is different from downloading a single named file.

cesiumcloud download --all "./CesiumCloud Restore"
cesiumcloud download --all "E:\RestoreAll" -simultaneous 20

The CLI supports up to 64 simultaneous downloads. Completed downloads are retained if a later transfer fails; verify important backups before removing their source copies.

Transfer progress and cancellation

Uploads and downloads show live progress as transfers occur. To stop active CLI transfers, open a second terminal on the same computer and run the matching cancel command.

cesiumcloud upload cancel
cesiumcloud download cancel

To cancel a particular incomplete server upload, use cesiumcloud cancel-upload UPLOAD_ID where supported. The two general cancel commands affect active local CLI transfers on that computer; they do not cancel website uploads or transfers started on other devices. Already completed files remain stored.

List files, sort, and paginate

Use list for a directory, -a for recursive listing, and -next to continue a paginated listing.

cesiumcloud list -a
cesiumcloud list -n 20
cesiumcloud list -next 20
cesiumcloud list -sort name
cesiumcloud list -sort size
cesiumcloud list -sort lastmodified
cesiumcloud list -long

The supported sort values are size, name, datecreated, lastmodified and reset. Large accounts may return results in multiple pages.

Search and navigate

Search by file name or another supported term, and use dir to change the CLI's current cloud directory.

cesiumcloud search "report"
cesiumcloud dir root/photos
cesiumcloud dir ..
cesiumcloud dir -

The website also provides account-wide search. Search results depend on account permissions and currently indexed files.

Rename, move, and delete

Rename files, move one or more files, or permanently delete a selected cloud path. CLI deletion is a permanent operation and is not the same as moving an item to website Trash.

cesiumcloud rename "root/old.txt" "new.txt"
cesiumcloud move "root/a.txt" [and] "root/b.txt" [to] root/archive
cesiumcloud delete "root/archive/old.txt"

Double-check deletion targets. Completed permanent deletions cannot be restored through the website Trash view.

SDK use in applications

The Python and JavaScript packages provide methods for working with authenticated account files, including uploads, listings, downloads, renames and deletions. For reliable transfers, prefer the official SDK's supported methods instead of implementing transfer retries or upload state management yourself.

See the installed package reference and cesiumcloud help for the client version you are using. Obtain an account credential through the supported authentication flow, and store it securely rather than embedding it in browser code or publishing it in a repository.

REST API authentication

The public REST API base URL is https://api.cesiummc.space/v1. Account endpoints require a valid account-scoped bearer credential; unauthenticated requests generally return HTTP 401.

curl "https://api.cesiummc.space/v1/me" \
  -H "Authorization: Bearer YOUR_ACCOUNT_CREDENTIAL"

Use credentials only over HTTPS. For browser application sign-in and file operations, use the supported CesiumCloud website session and official clients instead of exposing a credential to untrusted page scripts.

API account and health endpoints

These version 1 routes are available to clients with the appropriate permissions.

The examples use an illustrative bearer credential placeholder. Your SDK may provide a richer, paginated account catalog than the simple v1 file-list response.

API uploads and transfer grants

For uploads, use the current official SDK or CLI. The API includes authenticated transfer authorization and upload-session routes for compatible clients. Requests can be delayed, rejected or retried depending on account permissions, available quota, and current transfer state.

Use the supported client implementation for detailed request formats and sequencing. Do not treat a registration acknowledgment as proof that file data has finished uploading.

Downloads and integrity

Use the CLI or SDK to download files reliably. Clients support streaming, recovery of interrupted transfers where possible, and final completion checks. For a named download, specify the cloud path and optional local destination.

cesiumcloud download "root/docs/report.pdf" --location "./Restored"
cesiumcloud download --all "./Complete Restore"

A successful download should reproduce the complete original file. An interrupted download is not a finished backup; retry it and verify any important data before removing other copies.

HTTP errors and retries

API requests may return HTTP 400 for malformed input, 401 for missing or expired authentication, 403 for insufficient permission, 404 for unavailable or inaccessible items, 409 for a conflicting operation, and 429 or 5xx for temporary restrictions or service errors.

Read the response body when available. For temporary errors, honor a returned Retry-After header and retry with bounded backoff. Do not retry a destructive request blindly if its previous outcome is uncertain; check the operation's current status first.

Storage allocation and performance

Your account's allocated storage and remaining space determine whether new files can be accepted. A file upload may wait briefly when other transfers are active. Uploads and downloads have separate client concurrency controls, and increasing concurrency does not guarantee better speed.

For large batches, use the CLI's progress output and check final success and failure counts. A partial batch is not a complete backup; retry only files that did not finish.

Website file manager

Use Files to create folders and text files, upload files or folders, preview supported files, search, download, star, rename and move items. Starred collects items you have marked for quick access.

Select multiple files using their checkboxes. Hold Shift while clicking another checkbox to select the range between them. Dragging one of the selected files to a folder moves the selected group. Upload progress, cancellation, completed operations and errors are displayed within the application.

The top bar also includes Plans and Docs. The CesiumCloud logo returns to the “Your files, weightless” homepage.

Trash and automatic deletion

Items moved into Trash are automatically scheduled for permanent deletion 48 hours (2 days) after being placed there. Restore an item before that deadline to keep it. After the deadline or after choosing Delete forever, recovery through Trash is not available.

The interface removes an item once a permanent deletion has been accepted, although completion may still be in progress. Closing your browser does not cancel the accepted deletion. Verify that you have selected the correct items before deleting them.

Optional end-to-end encryption

Optional end-to-end encryption is available through cesiumcloud e2ee and the website's encryption controls. Encryption must be explicitly enabled: normal uploads are not automatically end-to-end encrypted. Filenames, folder paths, sizes and timestamps may remain visible.

cesiumcloud e2ee help
cesiumcloud e2ee keygen
cesiumcloud e2ee upload "./private-notes.txt"
cesiumcloud e2ee download "private-notes.txt.ccenc" --location "./Restored"
cesiumcloud e2ee migrate "root/docs/old.txt"

Save the recovery key offline. CesiumCloud cannot recover encrypted content if you lose the key. Migration leaves the original file intact unless you explicitly choose and confirm the documented removal options.

Plans, support, and troubleshooting

Check Plans for advertised plan information. Paid checkout is not yet available as an automated in-site purchase; paid plan buttons submit a genuine inquiry instead of activating a subscription. For assistance with access, password recovery, a failed transfer, or billing questions, use Contact.

Before reporting a transfer issue, note the client version (cesiumcloud --version), command attempted, approximate time, and the customer-facing error message. Do not include your account password, recovery key, authorization tokens, or other private credentials.