soreplicator 0.1.0__tar.gz

soreplicator-0.1.0/PKG-INFO

@@ -0,0 +1,221 @@
+Metadata-Version: 2.4
+Name: soreplicator
+Version: 0.1.0
+Summary: Simons Observatory REplicator server and command-line client
+License-Expression: MIT
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: boto3<2,>=1.40
+Requires-Dist: defusedxml<1,>=0.7.1
+Requires-Dist: fastapi<1,>=0.116
+Requires-Dist: httpx<1,>=0.28
+Requires-Dist: jinja2<4,>=3.1
+Requires-Dist: pydantic-settings<3,>=2.10
+Requires-Dist: python-multipart<1,>=0.0.20
+Requires-Dist: soauth<1,>=0.8.2
+Requires-Dist: socolors<1,>=0.0.8
+Requires-Dist: uvicorn[standard]<1,>=0.35
+Provides-Extra: dev
+Requires-Dist: pytest<9,>=8.4; extra == "dev"
+Requires-Dist: pytest-asyncio<2,>=1.1; extra == "dev"
+Requires-Dist: ruff<1,>=0.12; extra == "dev"
+
+SORE: Simons Observatory REplicator
+===================================
+
+SORE is a tool to ensure that a copy of your critical data is stored on all of our
+HPC machines. You can upload a file to SORE, and within an hour it should be
+replicated across NERSC, Princeton, and SO:UK. The system works by leveraging
+S3: we use Versity's S3 Gateway to allow you to upload data to the NERSC filesystem
+from anywhere in the world, and then a background Globus job ensures data is
+replicated to the other systems. You can only add and delete data that you have
+uploaded; no 'edit' functionality exists. You should also not attempt to
+directly modify data on disk at any of the sites (and this will be impossible
+anyway).
+
+To upload data, all you need to do is use the `sore` command-line utility:
+```bash
+sore -i local_file.fits -o testing/2026-01-01/local_file.fits
+```
+The `-i` input file is the path on your local filesystem. The `-o` output
+filename is the position in the global namespace that your file will take.
+Your file will then be uploaded, over the internet, to NERSC, where it will
+appear at `sore/$GITHUB_USERNAME/testing/2026-01-01/local_file.fits`. It will
+shortly be copied to other sites.
+
+Developed with the Codex/OpenAI 5.6 generation models.
+
+Getting set up
+--------------
+
+To get set up, you will first need to install the `soreplicator` python package:
+```bash
+uv pip install soreplicator
+```
+To authenticate with the system, you will need a username and password. These are
+_secrets_ and should never be shared with anyone else. To get your username
+and password, you will need to log into the web interface at
+https://sore.simonsobservatory.org/setup. Here, you will be able to get your username
+and password for the `sore` server. Your username will always be the same
+as your GitHub username.
+
+`sore` includes a utility to store these secrets for re-use in a safe location.
+We recommend using this. To set up `sore` you should call:
+```bash
+sore --setup
+```
+This will allow you to paste in your username and password, which will be saved
+in your config location (usually `~/.config/sore.json`) with `600` permissions.
+
+Deleting Files
+--------------
+
+Sometimes you will want to remove files from the system, because they are old and
+no longer used. You can do this with the `sore` command-line tool:
+```bash
+sore -d testing/2026-01-01/local-file.fits
+```
+Which will ask you to input `y/n` for whether you are sure you want to delete
+this file in the global namespace. Note that you can only change your own files,
+not anyone elses. If you are sure and want to avoid the prompt, you can use
+```bash
+sore -d testing/2026-01-01/local-file.fits -f
+```
+to force-delete without needing to respond to the prompt.
+
+Administrator Information
+-------------------------
+
+Setting up `sore` is easy. We provide a containerized version of the server. The most
+important thing to realize is that we provide one bucket per user, with the bucket
+name the same as their GitHub username. This allows us to set bucket-level permissions
+for each user, allowing them only `PUT`, `GET`, and `DELETE` access to these buckets,
+with `GET` permissions for all buckets.
+
+Included with this repository is a `nginx` configuration file that allows you to mount:
+- Versity's S3 Gateway on /
+- The provided `sore` server on `/setup`.
+- Sharing of directories for `.well-known` challenges.
+
+We authenticate users using the Simons Observatory authentication framework `soauth`.
+
+To set up `sore`, you will need an administrator credential (ideally not the root
+credential) that allows the creation of buckets and users with various levels of
+permissions. You should set the following environment variables:
+
+- `SORE_GATEWAY_USERNAME`: the username of the account that can create other accounts
+- `SORE_GATEWAY_PASSWORD`: the password of the account that can create other accounts
+- `SORE_GATEWAY_REMOTE_LOCATION`: the location of the gateway on the open internet
+- `SORE_GATEWAY_LOCAL_LOCATION`: the location of the gateway on the local network
+- `SORE_ADMIN_GRANT`: the `soauth` grant for administrator priviliges (`sore:admin`)
+- `SORE_USER_GRANT`: the `soauth` grant required for users to create accounts (`sore:user`)
+
+We will only communicate with the gateway on the local network and never over the
+open internet. The `REMOTE_LOCATION` is just for providing information in the UI.
+
+### Administrator Panels
+
+Within the Web UI, you can see information on all of the user accounts that have
+been created to date, and the buckets along with their sizes. This information is
+pulled dynamically from the S3 gateway and is not stored separately for the `sore`
+server so the `sore` server is effectively stateless. You will require the
+`SORE_ADMIN_GRANT` to view this page.
+
+Implementation
+--------------
+
+This repository contains the complete gateway edge, account service, and client:
+
+- `docker-compose.yml` runs VersityGW with a POSIX directory, sidecar metadata,
+  IAM, its WebGUI, the SORE server, and nginx.
+- `soreplicator/server/` is a stateless FastAPI service. It authenticates with `soauth`, creates
+  or rotates a VersityGW account, creates the matching bucket, and maintains a
+  bucket policy that gives every provisioned account read access while preserving
+  owner write/delete access.
+- `soreplicator/client/` supplies the `sore` command. Large files use four concurrent S3
+  multipart transfers with a terminal progress bar; smaller files use a regular
+  PUT. Both paths write conditionally, so an existing object cannot be
+  overwritten. Configuration is written atomically with mode `600` and insecure
+  remote HTTP endpoints are rejected.
+- The `/setup/admin` view queries users, buckets, object counts, and sizes directly
+  from VersityGW. No credentials or inventory are stored in an application database.
+
+The downstream Globus replication job is intentionally outside this repository's
+scope; it can consume the gateway's shared POSIX directory independently.
+
+### Local stack
+
+The included compose topology is a loopback-only development environment:
+
+```bash
+cp .env.example .env
+# Change the secrets and SORE_DEVELOPMENT_USERNAME in .env first.
+docker compose up -d --build
+```
+
+Open the following local endpoints:
+
+- SORE setup: `http://sore.localhost:8080/setup/`
+- VersityGW WebGUI through nginx: `http://gateway.localhost:8080/`
+- S3 through nginx: `http://s3.localhost:8080/`
+
+The WebGUI is preconfigured to use `s3.localhost` for S3 and `admin.localhost`
+for its admin API. Log in with the gateway administrator values from `.env`.
+Persistent objects, versions, IAM data, and metadata are stored under `./data`
+by default. Set `SORE_DATA_DIRECTORY` to share another host directory.
+
+The compose stack deliberately uses the fixed development identity named by
+`SORE_DEVELOPMENT_USERNAME`; nginx publishes only on `127.0.0.1`. Development
+authentication cannot start unless `SORE_DEBUG=true`. Never expose this mode to a
+network.
+
+### Production server configuration
+
+The Docker image runs as an unprivileged user with a read-only-compatible root
+filesystem. For production, set `SORE_AUTH_MODE=soauth`, `SORE_DEBUG=false`, and
+provide these settings to the server container:
+
+| Setting | Purpose |
+| --- | --- |
+| `SORE_GATEWAY_USERNAME` / `SORE_GATEWAY_PASSWORD` | Versity administrator credential |
+| `SORE_GATEWAY_REMOTE_LOCATION` | Public S3 URL displayed to clients |
+| `SORE_GATEWAY_LOCAL_LOCATION` | Private S3 URL used by the server |
+| `SORE_GATEWAY_ADMIN_LOCATION` | Private Versity admin API URL |
+| `SORE_GATEWAY_REGION` | SigV4 region; defaults to `us-east-1` |
+| `SORE_APP_BASE_URL` | Public application URL, including `/setup` |
+| `SORE_AUTHENTICATION_BASE_URL` | SOAuth service URL |
+| `SORE_APP_ID` / `SORE_CLIENT_SECRET` | SOAuth application credential |
+| `SORE_PUBLIC_KEY_FILE` | Mounted SOAuth public key path |
+| `SORE_KEY_PAIR_TYPE` | SOAuth key type; defaults to `Ed25519` |
+| `SORE_ADMIN_GRANT` / `SORE_USER_GRANT` | Required grants |
+
+Terminate TLS at nginx or an upstream load balancer, keep the admin API private,
+replace every development secret, and adapt `nginx/nginx.conf` to the production
+hostnames. The `.well-known` directory is mounted read-only for ACME challenges.
+
+### Development and verification
+
+```bash
+uv sync --extra dev
+uv run pytest
+uv run ruff check .
+npm install
+npm run build:css
+docker compose config
+```
+
+Tailwind output and htmx are vendored under `soreplicator/server/static`, so the setup UI does
+not depend on third-party CDNs. The Tailwind palette is the colorblind-friendly
+SO palette from `socolors`.
+
+### Releases
+
+GitHub Actions runs Ruff and the test suite on Python 3.11–3.13 for pull requests
+and pushes to `main`, and verifies that the committed Tailwind stylesheet is current.
+To publish a release, update the version in `pyproject.toml`, merge it to `main`,
+and publish a GitHub Release.
+
+The publishing workflow uses [PyPI Trusted Publishing](https://docs.pypi.org/trusted-publishers/)
+instead of a stored API token. Before the first release, configure a GitHub Actions
+Trusted Publisher for this repository and the `pypi` environment in the
+`soreplicator` PyPI project.

soreplicator-0.1.0/README.md

@@ -0,0 +1,199 @@
+SORE: Simons Observatory REplicator
+===================================
+
+SORE is a tool to ensure that a copy of your critical data is stored on all of our
+HPC machines. You can upload a file to SORE, and within an hour it should be
+replicated across NERSC, Princeton, and SO:UK. The system works by leveraging
+S3: we use Versity's S3 Gateway to allow you to upload data to the NERSC filesystem
+from anywhere in the world, and then a background Globus job ensures data is
+replicated to the other systems. You can only add and delete data that you have
+uploaded; no 'edit' functionality exists. You should also not attempt to
+directly modify data on disk at any of the sites (and this will be impossible
+anyway).
+
+To upload data, all you need to do is use the `sore` command-line utility:
+```bash
+sore -i local_file.fits -o testing/2026-01-01/local_file.fits
+```
+The `-i` input file is the path on your local filesystem. The `-o` output
+filename is the position in the global namespace that your file will take.
+Your file will then be uploaded, over the internet, to NERSC, where it will
+appear at `sore/$GITHUB_USERNAME/testing/2026-01-01/local_file.fits`. It will
+shortly be copied to other sites.
+
+Developed with the Codex/OpenAI 5.6 generation models.
+
+Getting set up
+--------------
+
+To get set up, you will first need to install the `soreplicator` python package:
+```bash
+uv pip install soreplicator
+```
+To authenticate with the system, you will need a username and password. These are
+_secrets_ and should never be shared with anyone else. To get your username
+and password, you will need to log into the web interface at
+https://sore.simonsobservatory.org/setup. Here, you will be able to get your username
+and password for the `sore` server. Your username will always be the same
+as your GitHub username.
+
+`sore` includes a utility to store these secrets for re-use in a safe location.
+We recommend using this. To set up `sore` you should call:
+```bash
+sore --setup
+```
+This will allow you to paste in your username and password, which will be saved
+in your config location (usually `~/.config/sore.json`) with `600` permissions.
+
+Deleting Files
+--------------
+
+Sometimes you will want to remove files from the system, because they are old and
+no longer used. You can do this with the `sore` command-line tool:
+```bash
+sore -d testing/2026-01-01/local-file.fits
+```
+Which will ask you to input `y/n` for whether you are sure you want to delete
+this file in the global namespace. Note that you can only change your own files,
+not anyone elses. If you are sure and want to avoid the prompt, you can use
+```bash
+sore -d testing/2026-01-01/local-file.fits -f
+```
+to force-delete without needing to respond to the prompt.
+
+Administrator Information
+-------------------------
+
+Setting up `sore` is easy. We provide a containerized version of the server. The most
+important thing to realize is that we provide one bucket per user, with the bucket
+name the same as their GitHub username. This allows us to set bucket-level permissions
+for each user, allowing them only `PUT`, `GET`, and `DELETE` access to these buckets,
+with `GET` permissions for all buckets.
+
+Included with this repository is a `nginx` configuration file that allows you to mount:
+- Versity's S3 Gateway on /
+- The provided `sore` server on `/setup`.
+- Sharing of directories for `.well-known` challenges.
+
+We authenticate users using the Simons Observatory authentication framework `soauth`.
+
+To set up `sore`, you will need an administrator credential (ideally not the root
+credential) that allows the creation of buckets and users with various levels of
+permissions. You should set the following environment variables:
+
+- `SORE_GATEWAY_USERNAME`: the username of the account that can create other accounts
+- `SORE_GATEWAY_PASSWORD`: the password of the account that can create other accounts
+- `SORE_GATEWAY_REMOTE_LOCATION`: the location of the gateway on the open internet
+- `SORE_GATEWAY_LOCAL_LOCATION`: the location of the gateway on the local network
+- `SORE_ADMIN_GRANT`: the `soauth` grant for administrator priviliges (`sore:admin`)
+- `SORE_USER_GRANT`: the `soauth` grant required for users to create accounts (`sore:user`)
+
+We will only communicate with the gateway on the local network and never over the
+open internet. The `REMOTE_LOCATION` is just for providing information in the UI.
+
+### Administrator Panels
+
+Within the Web UI, you can see information on all of the user accounts that have
+been created to date, and the buckets along with their sizes. This information is
+pulled dynamically from the S3 gateway and is not stored separately for the `sore`
+server so the `sore` server is effectively stateless. You will require the
+`SORE_ADMIN_GRANT` to view this page.
+
+Implementation
+--------------
+
+This repository contains the complete gateway edge, account service, and client:
+
+- `docker-compose.yml` runs VersityGW with a POSIX directory, sidecar metadata,
+  IAM, its WebGUI, the SORE server, and nginx.
+- `soreplicator/server/` is a stateless FastAPI service. It authenticates with `soauth`, creates
+  or rotates a VersityGW account, creates the matching bucket, and maintains a
+  bucket policy that gives every provisioned account read access while preserving
+  owner write/delete access.
+- `soreplicator/client/` supplies the `sore` command. Large files use four concurrent S3
+  multipart transfers with a terminal progress bar; smaller files use a regular
+  PUT. Both paths write conditionally, so an existing object cannot be
+  overwritten. Configuration is written atomically with mode `600` and insecure
+  remote HTTP endpoints are rejected.
+- The `/setup/admin` view queries users, buckets, object counts, and sizes directly
+  from VersityGW. No credentials or inventory are stored in an application database.
+
+The downstream Globus replication job is intentionally outside this repository's
+scope; it can consume the gateway's shared POSIX directory independently.
+
+### Local stack
+
+The included compose topology is a loopback-only development environment:
+
+```bash
+cp .env.example .env
+# Change the secrets and SORE_DEVELOPMENT_USERNAME in .env first.
+docker compose up -d --build
+```
+
+Open the following local endpoints:
+
+- SORE setup: `http://sore.localhost:8080/setup/`
+- VersityGW WebGUI through nginx: `http://gateway.localhost:8080/`
+- S3 through nginx: `http://s3.localhost:8080/`
+
+The WebGUI is preconfigured to use `s3.localhost` for S3 and `admin.localhost`
+for its admin API. Log in with the gateway administrator values from `.env`.
+Persistent objects, versions, IAM data, and metadata are stored under `./data`
+by default. Set `SORE_DATA_DIRECTORY` to share another host directory.
+
+The compose stack deliberately uses the fixed development identity named by
+`SORE_DEVELOPMENT_USERNAME`; nginx publishes only on `127.0.0.1`. Development
+authentication cannot start unless `SORE_DEBUG=true`. Never expose this mode to a
+network.
+
+### Production server configuration
+
+The Docker image runs as an unprivileged user with a read-only-compatible root
+filesystem. For production, set `SORE_AUTH_MODE=soauth`, `SORE_DEBUG=false`, and
+provide these settings to the server container:
+
+| Setting | Purpose |
+| --- | --- |
+| `SORE_GATEWAY_USERNAME` / `SORE_GATEWAY_PASSWORD` | Versity administrator credential |
+| `SORE_GATEWAY_REMOTE_LOCATION` | Public S3 URL displayed to clients |
+| `SORE_GATEWAY_LOCAL_LOCATION` | Private S3 URL used by the server |
+| `SORE_GATEWAY_ADMIN_LOCATION` | Private Versity admin API URL |
+| `SORE_GATEWAY_REGION` | SigV4 region; defaults to `us-east-1` |
+| `SORE_APP_BASE_URL` | Public application URL, including `/setup` |
+| `SORE_AUTHENTICATION_BASE_URL` | SOAuth service URL |
+| `SORE_APP_ID` / `SORE_CLIENT_SECRET` | SOAuth application credential |
+| `SORE_PUBLIC_KEY_FILE` | Mounted SOAuth public key path |
+| `SORE_KEY_PAIR_TYPE` | SOAuth key type; defaults to `Ed25519` |
+| `SORE_ADMIN_GRANT` / `SORE_USER_GRANT` | Required grants |
+
+Terminate TLS at nginx or an upstream load balancer, keep the admin API private,
+replace every development secret, and adapt `nginx/nginx.conf` to the production
+hostnames. The `.well-known` directory is mounted read-only for ACME challenges.
+
+### Development and verification
+
+```bash
+uv sync --extra dev
+uv run pytest
+uv run ruff check .
+npm install
+npm run build:css
+docker compose config
+```
+
+Tailwind output and htmx are vendored under `soreplicator/server/static`, so the setup UI does
+not depend on third-party CDNs. The Tailwind palette is the colorblind-friendly
+SO palette from `socolors`.
+
+### Releases
+
+GitHub Actions runs Ruff and the test suite on Python 3.11–3.13 for pull requests
+and pushes to `main`, and verifies that the committed Tailwind stylesheet is current.
+To publish a release, update the version in `pyproject.toml`, merge it to `main`,
+and publish a GitHub Release.
+
+The publishing workflow uses [PyPI Trusted Publishing](https://docs.pypi.org/trusted-publishers/)
+instead of a stored API token. Before the first release, configure a GitHub Actions
+Trusted Publisher for this repository and the `pypi` environment in the
+`soreplicator` PyPI project.

soreplicator-0.1.0/pyproject.toml

@@ -0,0 +1,61 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "soreplicator"
+version = "0.1.0"
+description = "Simons Observatory REplicator server and command-line client"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+dependencies = [
+    "boto3>=1.40,<2",
+    "defusedxml>=0.7.1,<1",
+    "fastapi>=0.116,<1",
+    "httpx>=0.28,<1",
+    "jinja2>=3.1,<4",
+    "pydantic-settings>=2.10,<3",
+    "python-multipart>=0.0.20,<1",
+    "soauth>=0.8.2,<1",
+    "socolors>=0.0.8,<1",
+    "uvicorn[standard]>=0.35,<1",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.4,<9",
+    "pytest-asyncio>=1.1,<2",
+    "ruff>=0.12,<1",
+]
+
+[project.scripts]
+sore = "soreplicator.client.cli:main"
+sore-server = "soreplicator.server.app:run"
+
+[tool.setuptools]
+packages = ["soreplicator", "soreplicator.client", "soreplicator.server"]
+include-package-data = false
+
+[tool.setuptools.package-data]
+"soreplicator.server" = [
+    "static/app.css",
+    "static/app.js",
+    "static/htmx.min.js",
+    "static/*.png",
+    "static/*.webmanifest",
+    "templates/*.html",
+    "templates/fragments/*.html",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"
+
+[tool.ruff]
+line-length = 88
+target-version = "py311"
+
+[tool.ruff.lint]
+extend-select = ["I", "B", "S", "UP"]
+ignore = ["S101"]

soreplicator-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

soreplicator-0.1.0/soreplicator/__init__.py

@@ -0,0 +1,3 @@
+"""Simons Observatory REplicator."""
+
+__version__ = "0.1.0"

soreplicator-0.1.0/soreplicator/client/__init__.py

@@ -0,0 +1,3 @@
+"""SORE command-line client."""
+
+__version__ = "0.1.0"

soreplicator-0.1.0/soreplicator/client/cli.py

@@ -0,0 +1,154 @@
+"""The ``sore`` command-line interface."""
+
+from __future__ import annotations
+
+import argparse
+import getpass
+import sys
+from pathlib import Path
+from typing import TextIO
+from urllib.parse import urlsplit
+
+from pydantic import ValidationError
+
+from soreplicator.client.config import (
+    ClientConfig,
+    config_path,
+    load_config,
+    save_config,
+)
+from soreplicator.client.storage import StorageError, delete, upload
+
+DEFAULT_ENDPOINT = "https://sore.simonsobservatory.org"
+
+
+def _human_bytes(value: int) -> str:
+    size = float(value)
+    for unit in ("B", "KB", "MB", "GB", "TB"):
+        if size < 1000 or unit == "TB":
+            return f"{size:.0f} {unit}" if unit == "B" else f"{size:.1f} {unit}"
+        size /= 1000
+    return f"{size:.1f} TB"
+
+
+class ProgressBar:
+    def __init__(self, total: int, stream: TextIO = sys.stderr, width: int = 28):
+        self.total = total
+        self.stream = stream
+        self.width = width
+        self.enabled = stream.isatty()
+        self.rendered = False
+        if self.enabled:
+            self.update(0, total)
+
+    def update(self, uploaded: int, total: int) -> None:
+        if not self.enabled:
+            return
+        fraction = 1.0 if total == 0 else min(1.0, uploaded / total)
+        filled = round(self.width * fraction)
+        bar = "#" * filled + "-" * (self.width - filled)
+        self.stream.write(
+            f"\rUploading [{bar}] {fraction:6.1%} "
+            f"{_human_bytes(uploaded)} / {_human_bytes(total)}"
+        )
+        self.stream.flush()
+        self.rendered = True
+
+    def close(self) -> None:
+        if self.rendered:
+            self.stream.write("\n")
+            self.stream.flush()
+            self.rendered = False
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="sore", description="Upload immutable files to the SORE replica service."
+    )
+    actions = parser.add_mutually_exclusive_group(required=True)
+    actions.add_argument(
+        "--setup", action="store_true", help="store gateway credentials"
+    )
+    actions.add_argument("-i", "--input", type=Path, help="local file to upload")
+    actions.add_argument(
+        "-d", "--delete", metavar="REMOTE_PATH", help="delete an object"
+    )
+    parser.add_argument("-o", "--output", help="remote path for an upload")
+    parser.add_argument(
+        "-f", "--force", action="store_true", help="skip delete confirmation"
+    )
+    parser.add_argument(
+        "--config", type=Path, default=config_path(), help=argparse.SUPPRESS
+    )
+    return parser
+
+
+def _setup(path: Path) -> int:
+    endpoint = (
+        input(f"Gateway endpoint [{DEFAULT_ENDPOINT}]: ").strip() or DEFAULT_ENDPOINT
+    )
+    parsed = urlsplit(endpoint)
+    if parsed.scheme not in {"http", "https"} or not parsed.netloc:
+        raise ValueError("endpoint must be an absolute HTTP(S) URL")
+    hostname = parsed.hostname or ""
+    is_loopback = hostname in {"localhost", "127.0.0.1", "::1"} or hostname.endswith(
+        ".localhost"
+    )
+    if parsed.scheme != "https" and not is_loopback:
+        raise ValueError(
+            "credentials may only be sent over HTTPS (except on localhost)"
+        )
+    username = input("Username: ").strip()
+    password = getpass.getpass("Password: ")
+    if not password:
+        raise ValueError("password cannot be empty")
+    destination = save_config(
+        ClientConfig(endpoint=endpoint, username=username, password=password), path
+    )
+    print(f"Credentials saved to {destination} with mode 600.")
+    return 0
+
+
+def _confirm_delete(remote_path: str) -> bool:
+    answer = input(f"Delete {remote_path!r} permanently? [y/N] ").strip().lower()
+    return answer in {"y", "yes"}
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    try:
+        if args.setup:
+            if args.output or args.force:
+                parser.error("--setup cannot be combined with -o or -f")
+            return _setup(args.config)
+
+        config = load_config(args.config)
+        if args.input:
+            if not args.output:
+                parser.error("-o/--output is required with -i/--input")
+            if args.force:
+                parser.error("-f/--force is only valid with -d/--delete")
+            progress = ProgressBar(args.input.stat().st_size)
+            try:
+                upload(config, args.input, args.output, progress.update)
+            finally:
+                progress.close()
+            print(f"Uploaded {args.input} to sore/{config.username}/{args.output}")
+            return 0
+
+        if args.output:
+            parser.error("-o/--output is only valid with -i/--input")
+        if not args.force and not _confirm_delete(args.delete):
+            print("Delete cancelled.")
+            return 0
+        delete(config, args.delete)
+        print(f"Deleted sore/{config.username}/{args.delete}")
+        return 0
+    except (OSError, PermissionError, ValueError, ValidationError, StorageError) as exc:
+        print(f"sore: {exc}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())