Metadata-Version: 2.4
Name: cesiumcloud
Version: 0.2.35
Summary: CesiumCloud cloud storage Python SDK and command-line client
Author: CesiumCloud
Project-URL: Homepage, https://cloud.cesiummc.space/
Project-URL: Documentation, https://api.cesiummc.space/docs
Keywords: cesiumcloud,cloud,storage,backup
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Environment :: Console
Classifier: Topic :: Internet
Classifier: Topic :: System :: Archiving :: Backup
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: cryptography>=42

# CesiumCloud — Python CLI and SDK

**Release 0.2.35 · Python 3.10+ · Windows, macOS and Linux**

The Python package provides a CesiumCloud command-line client and Python APIs for authorized storage operations. It is independent of the Node.js CLI and does not require Node.js.

Web app: https://cloud.cesiummc.space/app/ · PyPI: https://pypi.org/project/cesiumcloud/

## Installation

Use a virtual environment when possible:

```bash
python -m venv .venv
```

Activate the environment with `.venv\Scripts\activate` in Windows CMD, `.venv\Scripts\Activate.ps1` in PowerShell (if local policy permits), or `source .venv/bin/activate` in Linux/macOS. Alternatively call the environment's Python executable directly.

```bash
python -m pip install --upgrade cesiumcloud==0.2.35
python -m cesiumcloud --version
python -m cesiumcloud authenticate
python -m cesiumcloud whoami
```

You can run `cesiumcloud` instead of `python -m cesiumcloud` when its executable is on PATH. Device authorization opens a browser flow; a manually created API key is not necessary for interactive use. `cesiumcloud upgrade` and `update` install the current release from official PyPI.

**Ubuntu/Debian:** if your OS restricts global pip, use `python3 -m venv` and install into that environment. Python 3.10+ is required; `cryptography>=42` is the package's declared dependency for encryption.

## File and directory commands

```bash
cesiumcloud upload "./backup.zip"
cesiumcloud upload "./Projects"
cesiumcloud upload "./backup.zip" --replace
cesiumcloud upload "./a.zip" [and] "./b.zip" -simultaneous 2
cesiumcloud list -a
cesiumcloud list -n 20 -sort name
cesiumcloud search ext:png
cesiumcloud dir /
cesiumcloud dir "photos"
cesiumcloud download "backup.zip"
cesiumcloud download "photos" --location "./Restored"
cesiumcloud download --all "./RestoreAll"
cesiumcloud rename "old.txt" "new.txt"
cesiumcloud move "a.txt" [to] "archive"
cesiumcloud delete "archive/a.txt"
```

**Command reference:** `authenticate`, `whoami`, `logout`, `upgrade`, `update`, `stats`, `upload`, `download`, `upload cancel`, `download cancel`, `uploads`, `cancel-upload`, `discard-upload`, `resume-upload` (legacy), `list`, `search`, `dir`, `rename`, `move`, `delete`, `e2ee` and `help`. Use `cesiumcloud help COMMAND` or `cesiumcloud COMMAND --help` for detailed syntax.

Literal `[and]` separates multiple inputs; `[to]` (or `to`) separates sources from a move destination. Quote local filenames with spaces or parentheses. Relative cloud paths resolve from the saved cloud directory selected with `dir`; the `root/` prefix refers to the cloud root rather than a local filesystem directory.

### Downloads and folder restoration

A named download saves to the OS Downloads directory unless `--location DIRECTORY` is specified. Existing local files are preserved by choosing a numbered filename. Folder downloads preserve nested paths and empty folders beneath the selected destination. `download --all LOCALDIR` restores the full account hierarchy. `-simultaneous N` / `--simultaneous N` permits 1–64 active downloads (default 1). Uploading folders or multiple files supports up to 40 active uploads by default for folders.

### Browsing

`list` shows 15 files by default; `-a` lists recursively; `-n N`, `N` and `-N` specify count; `-next N` advances the list cursor; `-sort size|name|datecreated|lastmodified|reset` controls order; `-long` adds metadata. `search` finds case-insensitive matches in cloud paths; `ext:png` matches a file extension. `dir ..` moves up, `dir /` returns to root, and `dir` with no argument displays the current cloud directory. `rename` preserves a file extension unless `-ne` is used.

## Upload behavior, cancellations and options

Python single-file uploads default to **99,876,864-byte chunks** (aligned under 100 MB), matching Node.js. Uploads of directories or multiple files use the batched transfer path with separate file progress and admission controls.

The Python CLI supports the following upload chunk variables:

| Environment variable | Accepted setting | Effect |
| --- | --- | --- |
| `CESIUMCLOUD_UPLOAD_CHUNK_MIB` | `64` or `95` | Optional smaller chunks; default is aligned 100 MB |
| `CESIUMCLOUD_UPLOAD_CHUNK_MB` | `100` | Selects 99,876,864-byte aligned chunks, overriding the MiB variable |
| `CESIUMCLOUD_CONFIG_DIR` | Local directory | Uses alternate saved authorization and local settings |
| `CESIUMCLOUD_API_KEY` | Authorized device token | Optional for automated SDK/CLI use; keep private |

Near-100 MB is the Python default. Every chunk is capped at 100 MB, including SDK overrides. Node-specific read-ahead and stream-block settings do not apply.

For Bash:

```bash
CESIUMCLOUD_UPLOAD_CHUNK_MB=100 cesiumcloud upload "./backup.zip"
```

For PowerShell:

```powershell
$env:CESIUMCLOUD_UPLOAD_CHUNK_MB = "100"
cesiumcloud upload "E:\Backup\backup.zip"
Remove-Item Env:\CESIUMCLOUD_UPLOAD_CHUNK_MB
```

**Cancellation:** `Ctrl+C` interrupts the Python CLI when the terminal forwards it. Alternatively, run `cesiumcloud upload cancel` or `cesiumcloud download cancel` from a second terminal on the same computer and configuration. A cancelled/failed upload is **discarded**, not paused for future resumption. Upload transport may retry an unacknowledged chunk during a continuing session; that is not a persistent resume feature. Use `cesiumcloud uploads` to inspect any pending cleanup. Completed cloud files survive cancellation; successful local downloads survive cancelled batches.

The Windows-specific raw console Ctrl+C fallback introduced in the **Node.js** CLI 0.2.29 does not automatically apply to the Python CLI. Use the second-terminal cancellation command if your Python terminal does not deliver the interrupt.

## Python SDK

Prefer `IsolatedTransferClient` for individually managed cloud files. It requires an authorized device token, obtainable through the normal login process for your account; use an environment variable rather than embedding tokens in code.

```python
import os
from pathlib import Path
from cesiumcloud import IsolatedTransferClient

storage = IsolatedTransferClient(os.environ["CESIUMCLOUD_API_KEY"])
storage.upload_file(Path("notes.txt"), "docs/notes.txt")
files = storage.all_files()
match = next((item for item in files if item["path"] == "docs/notes.txt"), None)
if match is not None:
    storage.download_file(match["id"], Path("notes-restored.txt"))
```

Additional supported operations include `upload_path`, `download_path`, `list_files`, `find_path`, `directory_exists`, `mkdir`, `rmdir`, `rename_file`, `move_folder`, `delete_file`, `pending_uploads`, `cancel_upload`, `discard_upload` and `status`.

The package also exposes `CesiumCloudClient` for device authorization and compatible high-level methods:

```python
from cesiumcloud import CesiumCloudClient

client = CesiumCloudClient()
profile = client.authenticate()
print(profile.get("email", "CesiumCloud account"))
```

SDK downloads do not automatically rename files that already exist; the `overwrite` option must be considered explicitly when restoring to an existing local path. See the complete [SDK reference](https://github.com/v12-enginee/cesiumcloud-clients-release/blob/main/docs/SDK_REFERENCE.md).

## Local end-to-end content encryption (optional)

```bash
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"
```

The recovery key is stored locally in the CesiumCloud configuration directory. **Back it up securely offline**; if it is lost, CesiumCloud cannot recover encrypted contents. Plain `upload` remains unencrypted. Encrypted file contents are protected, but filenames, sizes, paths and usage metadata are not. Migrating plaintext to an encrypted copy preserves the original unless both `--purge-original` and `--i-backed-up-key` are specified.

## Troubleshooting

| Problem | Guidance |
| --- | --- |
| Command not found after install | Use `python -m cesiumcloud` in the environment where pip installed the package |
| Global pip installation blocked | Create a virtual environment |
| File path with spaces/parentheses not found | Quote the full pathname; do not rely on shell argument reconstruction |
| Existing cloud file | Use `--replace` only when intended |
| Incomplete/cancelled upload | It is not retained for normal resumption; inspect `cesiumcloud uploads` for pending cleanup |
| Ctrl+C intercepted on Windows | Run `cesiumcloud upload cancel` from a second terminal |
| Storage or quota error | Review `cesiumcloud stats`, reduce concurrency, and retry after capacity is available |
| Cannot decrypt file | Restore the correct offline recovery key |

**Important:** CLI delete moves completed files to Trash for 48 hours. Keep independent backups of important files and your encryption key. `logout` removes local authorization but does not revoke the device on the service.

For the current command matrix and complete guides, see https://cloud.cesiummc.space/api-docs.html and the documentation bundled with the client source.
### 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.
