CLI

The PutFS client command-line interface works similar like awscli or mc (the old minio client). Sync (bulk transfers) is multi-threaded by default.

pip install putfs[client]

Authentication

Via flags or environment variables:

# Environment (recommended)
export PUTFS_API_KEY=my-key
export PUTFS_API_SECRET=my-secret
export PUTFS_ENDPOINT_URL=http://localhost:8000

# Or per-command
putfs --key my-key --secret my-secret <command>

Commands

sync

Sync files between any two stores. Uses threaded parallel transfers with streaming (no buffering).

# Local directory → PutFS
putfs sync /data/exports http://localhost:8000/acme/exports

# PutFS → local directory
putfs sync http://localhost:8000/acme/exports /backup/exports

# Between two PutFS instances
putfs sync http://primary:8000/acme http://secondary:8000/acme

# Force re-upload everything (skip diff checks)
putfs sync --overwrite /data/exports http://localhost:8000/acme/exports

# Delete extra files on target
putfs sync --delete /data/exports http://localhost:8000/acme/exports

# Control parallelism (default: CPU count)
putfs sync -w 16 /data/exports http://localhost:8000/acme/exports

Without --overwrite, sync compares mtime (with size as fallback) and skips unchanged files. Without --delete, only the source is listed – the target is not scanned upfront.

ls

# List all keys
putfs ls http://localhost:8000/acme/

# With glob filter
putfs ls --glob "*.json" http://localhost:8000/acme/invoices/

# Exclude prefix
putfs ls --exclude-prefix temp/ http://localhost:8000/acme/

cp

Copy a single file between stores.

# Upload
putfs cp /local/file.pdf http://localhost:8000/acme/file.pdf

# Download
putfs cp http://localhost:8000/acme/file.pdf /local/file.pdf

# Between stores
putfs cp s3://bucket/file.pdf http://localhost:8000/acme/file.pdf

rm

# Delete a single file
putfs rm http://localhost:8000/acme/old-file.pdf

# Delete all files under a prefix
putfs rm --recursive http://localhost:8000/acme/temp/

URI schemes

URI	Store type
`https://host:port/path`	PutFS server (or any http server with file listings for read-only)
`/local/path`	Local filesystem
`s3://bucket/key`	S3-compatible (via anystore)
`gs://bucket/key`	Google Cloud Storage (via anystore)

Any URI supported by anystore (via fsspec) works as source or destination.