Metadata-Version: 2.4
Name: cesiumcloud
Version: 0.2.30
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.30 · 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.30
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 **64 MiB chunks**; this differs from the Node.js CLI's newer ~100 MB default. 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 `512` | Default `64` MiB; optional 512 MiB experiment |
| `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 |

The near-100 MB setting is opt-in for Python; a 512 MiB request may fall back to near-100 MB after HTTP 413, depending on the operation. Larger chunks use more RAM. Node-specific variables for HTTP stream blocks, prefetch, and experimental parallel lanes are **not** Python upload tuning controls.

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:** `delete` is permanent. 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.
