Metadata-Version: 2.4
Name: cesiumcloud
Version: 0.1.16
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 for Python

CesiumCloud cloud storage client for Python 3.10+.

## Installation

Install the latest version from PyPI:

    python -m pip install cesiumcloud

Or install the official wheel directly:

    python3 -m pip install https://cloud.cesiummc.space/clients/cesiumcloud-0.1.5-py3-none-any.whl

## Command-line use

    python -m cesiumcloud authenticate
    python -m cesiumcloud upload "/home/user/Documents"
    python -m cesiumcloud upload "/home/user/dogimages.zip"
    python -m cesiumcloud download "/home/user/Restored"
    python -m cesiumcloud whoami

The cesiumcloud command is equivalent to python3 -m cesiumcloud.

## Ubuntu 22.04, 24.04, 26.04 LTS and 26.10

Use Python 3.10 or newer. This Python client uses only the standard library
and does not require Node.js.

On Ubuntu, use a virtual environment instead of changing the system Python:

    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 https://cloud.cesiummc.space/clients/cesiumcloud-0.1.5-py3-none-any.whl
    "$HOME/.local/share/cesiumcloud/venv/bin/cesiumcloud" authenticate
    "$HOME/.local/share/cesiumcloud/venv/bin/cesiumcloud" upload "$HOME/Videos/My video.mp4"

The CLI accepts a single path containing spaces even when it is unquoted,
but quoting paths is still recommended. Authentication keeps the existing
~/.cesiumcloud/credentials.json.

Large uploads display transport-send progress in 256 KiB increments.
99% means data has been handed to the transport but may await server response;
100% appears only after the storage server commits the upload. The Python
client does not yet maintain resumable checkpoints across separate processes.

## Python SDK

    from cesiumcloud import CesiumCloudClient

    client = CesiumCloudClient()
    client.authenticate()
    client.upload("/home/user/dogimages.zip")
    files = client.list_files()
    print([file["name"] for file in files])
    client.download("/home/user/Restored")

Authentication uses your CesiumCloud account without copying an API key.
The Python implementation requires no Node.js runtime or third-party Python dependencies.

## Current limitations

Data is streamed directly from local files. The Python client does not yet maintain
restart-safe checkpoints across processes. Existing destination files are not
silently overwritten. Keep an independent backup of important data.

## Access management

Revoke credentials from the CesiumCloud dashboard. The logout command removes local credentials only.

## Existing accounts

CesiumCloud connects to the existing API and stores credentials in ~/.cesiumcloud/credentials.json. Existing CesiumCloud package installations are not modified.


### PowerShell filenames with parentheses
PowerShell treats unquoted parentheses as shell syntax and may remove them
before a program receives command arguments. Quote the **entire** path:

    cesiumcloud upload "E:\\Downloads\\Roblox 2026-10-18 13-37-47 (1).mp4"

The CLI joins unquoted fragments containing ordinary spaces, but cannot
reconstruct text that the shell has discarded. Version 0.1.5 displays
matching filenames and complete quoted examples when the supplied path
does not exist; it never guesses and uploads the wrong file.


## Reliable Python restore (0.1.5)

The Python CLI restores all committed files into a chosen directory.
Data is downloaded in bounded chunks, using authenticated HTTP byte-range
requests to resume incomplete or prematurely terminated file segments.
A successful restore checks every restored file's expected size.

If a previous restore stopped, use a NEW directory when retrying; partial
files in the old destination are left for inspection and are never deleted
silently. A restore is not a selective single-file fetch; it reconstructs
the account's committed backup set.

Only retry/download traffic changes; uploading still uses two Worker writes
per new pack, plus account and other metadata requests as applicable.


## Browse, search, rename, and permanently delete (0.1.6)

Python and npm CLIs share an account-backed file catalog.

    cesiumcloud list                   # root, 15 items, size descending
    cesiumcloud list -10               # 10 items
    cesiumcloud list -a                # all files, recursively
    cesiumcloud list -100 images/dogs  # directory entries
    cesiumcloud list -next 15 images/dogs
    cesiumcloud list -sort name        # persistent for future lists
    cesiumcloud list -sort lastmodified
    cesiumcloud list -sort datecreated
    cesiumcloud list -sort reset       # size sorting
    cesiumcloud list -10 images/dogs [and] images/cats
    cesiumcloud search puppy
    cesiumcloud search .png            # extension
    cesiumcloud search ext:jpg
    cesiumcloud dir images/dogs        # enter directory
    cesiumcloud dir ..                 # parent
    cesiumcloud dir -                  # previous visited directory
    cesiumcloud dir /                  # root
    cesiumcloud rename images/dogs/a.png b      # keeps original .png
    cesiumcloud rename images/dogs/a.png b -ne  # drops extension
    cesiumcloud delete images/dogs/a.png
    cesiumcloud delete -resume

List shows file extensions, file sizes, last modified and upload timestamps
in local time. Creation timestamps are captured for new uploads when
the source filesystem provides them; older packs fall back to upload time.

Permanent delete is not hide-only. Files may share immutable backup packs,
so the CLI stages replacements for surviving files, cuts over to verified
replacements, and deletes the old backing storage objects. The service
checks that removed backing storage objects are absent before reclaiming
their storage accounting. Use delete -resume after an interrupted purge.
Deletion is irreversible and needs temporary free quota for replacement
packs. Folders are not deleted recursively by default.

For multiple directories, quote the complete expression with the pipe
character, since an unquoted pipe is shell syntax. The program accepts
separately quoted directory arguments too. ZIP archives are not expanded
by list: extract and upload a folder to browse inside it.


## Fast file listing in 0.1.7

Versions 0.1.6 and earlier reread two storage metadata ranges from every
backup pack, sequentially, on every list/search/dir command. This could appear
to hang on an account containing many packs.

Version 0.1.7 uses an authenticated, account-isolated index stored in the edge service
service database: GET /v1/catalog/index?cursor=N. Immutable pack metadata is cached after
validation, including when new packs are committed. A first catalog read on an
older account may build this index; subsequent reads use service database. Cloud directories
and filenames remain identical to previous versions.

Navigation to /, .., and - is local; it does not need API access. Other
directory lookups use the indexed catalog. No user file contents are stored
in the metadata index (only paths, sizes, timestamps and pack segment locations).


## SQL-indexed file browsing (0.1.8)

All listing, searching, sorting, pagination and remote-directory existence
checks are now server-side indexed queries against CesiumCloud metadata index.
A list -10 request returns only ten entries plus their directory count.
It does not loop through packs, download remote metadata, load the
whole catalog into the CLI, or read any user file contents.

A persistent file_catalog_segments index is written at the same time
a new immutable backup pack's metadata is committed. Existing packs
are backfilled from the already-cached metadata, once, without downloading
the original packs. Physical backing storage deletion and pack replacement
remain unchanged; visibility switches and pack deletion are reflected by
the indexed queries.

A file's stored byte size (including 64 GB or larger) does not change
the cost of browsing. Directory navigation to root, parent and history is
handled locally. The API uses /v1/catalog/browse with mode, dir,
sort, limit, offset and search as optional parameters.


## Readable terminal listings (0.1.9)

By default, list and search output an aligned, responsive terminal table with
filename, extension or directory marker, human-readable file size, and short
local timestamps, e.g. 2026-10-27 10:17. Repeated labels have been removed
from each file row.

The renderer adapts to 40- to 160-column terminals. On narrow consoles it
shows fewer columns rather than wrapping each entry; long names are clipped
in the middle while preserving their endings. To show the COMPLETE names
and metadata in multiple lines, run:

    cesiumcloud list -long
    cesiumcloud list -long 20 images
    cesiumcloud search .png -long

All of these commands list 20 items:

    cesiumcloud list 20
    cesiumcloud list -20
    cesiumcloud list -n 20
    cesiumcloud list --limit 20

Previously 'list 20' was mistakenly interpreted as the directory '/20' and
printed zero items. It is now accepted as a numeric limit.

The API-backed SQL listing, file contents, download behavior, physical
Drive deletion and authentication are unchanged. This is a CLI-only release.


## Download an individual cloud file to a local folder (0.1.10)

Select just one cloud file with --location:

    cesiumcloud download dog.png --location "C:/Users/matth/Desktop"
    cesiumcloud download "images/dogs/dog.png" --location "E:/Downloads"
    cesiumcloud download "photos/picture (1).jpg" --location "./restored"

A relative cloud file name is resolved within the virtual directory selected
with cesiumcloud dir. An explicit cloud path can include nested directories.
The file is saved directly into the requested local folder under its original
basename (the CLI does not recreate parent folders for this selected download).
If no extension was included, the server resolves it only when there is
a single unambiguous match; otherwise include the extension.

This is a real single-file download, not a full backup restore: the CLI
requests only the file's segment metadata from CesiumCloud metadata index and streams its
segments from backing storage. In the normal case it makes one Worker metadata
request plus one Worker download request per nonempty segment (retries may
add requests). An empty file is created without a segment-download request.

Downloads write to a temporary file and are made visible at the destination
only after the complete expected size is received. Existing files are NEVER
overwritten. Partial files are cleaned up after a failed transfer.

Backward compatibility: cesiumcloud download "E:/restore-all" without
--location still restores the entire cloud backup collection to that
directory, as it did previously.


CESIUMCLOUD CLI REFERENCE — Python and npm (0.1.16)
====================================================
Usage: cesiumcloud COMMAND [arguments]. Use cesiumcloud help for this reference.
Linux/macOS examples use / paths; Windows examples use quotes around local paths.

ACCOUNT
  cesiumcloud authenticate                     Approve device code at CesiumCloud website
  cesiumcloud whoami                           Show signed-in account
  cesiumcloud logout                           Remove local CLI credential; does not revoke key remotely

UPLOAD / DOWNLOAD
  cesiumcloud upload "E:\Downloads\dog.png"      Upload local file
  cesiumcloud upload "./My Documents"          Upload local folder (recursively)
  cesiumcloud download "E:\restore"             Full-account restore into local folder
  cesiumcloud download dog.png --location "E:\Downloads"
  cesiumcloud download "images/dog.png" --location "E:\Downloads"
      Download ONLY one named cloud file into the local folder. The folder is
      created if needed. Existing local files are never overwritten. Relative
      filenames use the current cloud directory set by cesiumcloud dir.
      Quote local Windows paths and names containing spaces/parentheses.

BROWSING
  cesiumcloud list                             List 15 items of current cloud directory
  cesiumcloud list -10                         List 10 items
  cesiumcloud list 20                          List 20 items (also -n 20)
  cesiumcloud list -a                          List all files (paginated)
  cesiumcloud list -long                       Show full names and metadata
  cesiumcloud list -next 15                    Next 15 results after list
  cesiumcloud list -10 images/dogs [and] images/cats
  cesiumcloud list -sort size                  Default sorting (largest first)
  cesiumcloud list -sort name                  Persist sort by name
  cesiumcloud list -sort lastmodified          Persist newest-modified-first sorting
  cesiumcloud list -sort datecreated           Persist newest-created-first sorting
  cesiumcloud list -sort reset                 Reset sort to size
  cesiumcloud search dog.png                   Search filename
  cesiumcloud search .png                      Search extension
  cesiumcloud search ext:png                   Search extension (alternate)
  cesiumcloud search dog [and] .png           Search multiple terms
  cesiumcloud dir                              Go to cloud root and show it
  cesiumcloud dir images/dogs                  Change virtual directory
  cesiumcloud list -5 dogs [and] cats         List multiple directories
  cesiumcloud dir ..                           Up to parent directory
  cesiumcloud dir -                            Back in navigation history
  cesiumcloud dir /                            Go to root directory

RENAME (changes virtual filename; same stored bytes)
  cesiumcloud rename dog.png cat.png
  cesiumcloud rename root/images/dog.png cat.png
  cesiumcloud rename root/images/dog.png cat -ne
      Without -ne, omitted NEW extension inherits the original one.
      With -ne, remove the original extension if new name has none.
      A plain new name stays in the original file's cloud directory.
      Rename refuses existing target paths. Folder rename not supported;
      use move for entire directories.

MOVE (changes virtual paths, without transferring or rewriting file bytes)
  cesiumcloud move root/images/dog.png to root/things
  cesiumcloud move root/passwords.txt [and] root/securitypasswords.txt [to] root/important/secure/critical
  cesiumcloud move root/images [and] root/notes [to] root/archived
  cesiumcloud move images/dog.png [and] images/cat.png [to] root/things
  cesiumcloud move root/things/dog.png to root
      Accepts file and whole-directory sources (1-20 sources per invocation,
      max 1000 affected files). Directory moves preserve their folder name
      and subfolders. File moves preserve original basenames/extensions.
      Destination directories are virtual and created automatically as needed.
      Move rejects target collisions, duplicate sources, and recursive moves.
      The server applies each batch of path changes in one service database transaction.
      These are logical CesiumCloud paths, NOT local filesystem paths.

DELETE (PERMANENT, not recoverable through the CLI)
  cesiumcloud delete dog.png
  cesiumcloud delete root/images/dog.png [and] root/notes/old.txt
  cesiumcloud delete root/images/dog.png root/notes/old.txt
  cesiumcloud delete -resume                  Finish a pending physical removal
      Files are permanently removed from backing storage, not just hidden.
      Other files that share storage packs are preserved and verified.
      Each selected file is processed in sequence; batch delete is not atomic.
      Directory deletion is deliberately unavailable.

PATHS & SHELL RULES
  root/ is the top of YOUR authenticated cloud namespace (for rename,
  move, delete). Bare filenames use the current virtual directory.
  For browsing, use '/' as root, e.g. 'cesiumcloud list -10 /'.
  Use [and] to separate multiple files or directories without quotes.
  This works in Windows CMD, PowerShell, Bash and Zsh. A shell pipe
  is NOT a CesiumCloud separator. Quote paths containing spaces.
  Use 'to' or the literal '[to]' as the move destination separator.
  Put quotes around paths containing spaces or special shell characters.
  An extensionless filename matches only when unambiguous; otherwise
  include its extension. '/' is the cloud separator, not Windows '\'.

MORE HELP
  cesiumcloud help
  cesiumcloud --help
  cesiumcloud move --help
  cesiumcloud rename --help
  cesiumcloud delete --help
  cesiumcloud list --help

FILE MANAGEMENT GUARANTEES
  Browsing uses indexed metadata rather than streaming file payloads.
  Move/rename do not rewrite payload bytes. Single-file download streams
  only the requested segments. Delete is destructive and can require
  repacking unaffected files; resume cleanup if interrupted.


Live selected-file download progress (v0.1.16): The CLI updates the same terminal line with Downloading: N% (received/total bytes). The percentage is calculated exclusively from bytes received by the existing transfer stream and adds zero HTTP requests or extra Worker invocations. 100% appears only after the complete file is verified and committed to disk; if an interrupted segment needs a retry, only its missing bytes count toward progress. Download requests themselves are unchanged.


## Optional E2EE content encryption (0.1.16)

CesiumCloud supports EXPLICITLY OPTED-IN AES-256-GCM file-content encryption
using authenticated 1 MiB chunks and HKDF-SHA256. Python, Node and the browser
support the same interoperable CCENC01 format. This does NOT encrypt filenames,
directory paths, file sizes, dates, or activity metadata.

Existing uploads, backups and ordinary (non-E2EE) uploads remain unencrypted.

Generate a local recovery key (once, with no cloud requests):

    cesiumcloud e2ee keygen

Make an OFFLINE backup of ~/.cesiumcloud/e2ee-recovery.key immediately.
Windows location: %USERPROFILE%/.cesiumcloud/e2ee-recovery.key
If this recovery key is lost, CesiumCloud cannot recover encrypted contents.
Never upload the key file, paste it into support tickets, or share it in chats.

Encrypt and upload a single local file:

    cesiumcloud e2ee upload "My confidential report.pdf"

Download encrypted ciphertext and decrypt on your computer:

    cesiumcloud e2ee download "My confidential report.pdf.ccenc" --location "E:/Downloads"

Local-only encryption and decryption:

    cesiumcloud e2ee encrypt "My report.pdf" --location "E:/encrypted"
    cesiumcloud e2ee decrypt "E:/encrypted/My report.pdf.ccenc" --location "E:/restored"

Browser: In the file-manager E2EE panel, paste the same recovery key and unlock
it for the tab; confirm you backed it up offline, then check Encrypt selected
files. For small encrypted files click Decrypt & download. For encrypted files
above 32 MiB, use Python/npm CLI (browser currently limits local decryption).

Only ciphertext passes to the server during opted-in E2EE uploads. The crypto
adds ZERO Worker requests per encrypted chunk; regular transfer/retry/control
requests remain. Encrypted CLI uploads stage local ciphertext in a temporary
file, requiring enough free disk space. Ordinary file handling is unchanged.

This is opt-in content encryption, not a guarantee that every customer file is
E2EE or that filenames/metadata are invisible.


## Safe opt-in migration of existing plaintext cloud files (0.1.16)

When your OFFLINE recovery key is securely backed up, migrate ONE older file:

    cesiumcloud e2ee migrate "root/app/index.html"

CesiumCloud downloads the existing plaintext file to temporary LOCAL storage,
encrypts it locally with your key, uploads ciphertext to the same cloud folder,
downloads the ciphertext again, authenticates all chunks, and compares the
recovered SHA-256 hash against the original. It retains the original plaintext
file by default, so you can independently confirm restoration with another
device BEFORE physically deleting it:

    cesiumcloud delete "root/app/index.html"

For explicit automatic physical removal ONLY after a verified round-trip, use
BOTH flags:

    cesiumcloud e2ee migrate "root/app/index.html" --purge-original --i-backed-up-key

This final option permanently removes the original from ACTIVE storage after
verified SHA-256 equality. Backups and provider retention may keep historical
plaintext copies separately. NEVER use --purge-original until your recovery
key has been backed up offline and recovery verified on another device.

Migration requires sufficient FREE LOCAL DISK to hold a plaintext download and
encrypted staging (roughly twice file size). An interrupted encrypted upload
keeps its ciphertext checkpoint for safe retries. The filename, file size,
directory structure, modification times and account activity remain visible.
Migration is not automatic, does not rewrite unrelated files, and DOES NOT
make the entire existing account encrypted.

Python respects CESIUMCLOUD_CONFIG_DIR for isolated credentials, E2EE key,
and CLI navigation state, matching the npm client. The /app/app navigation
bug and directory renaming are fixed in both clients.
