Install

Two downloads and a self-test. The test checks the tool's own cryptography against known answers generated from the app's crypto, including that its encryption produces byte-identical output. If the test passes, the tool is trustworthy; if it fails, stop.

Expect a list of pass lines ending in all vectors pass. You can also confirm the download is the published release by comparing shasum -a 256 quattle.py against the hash ledger at quattle.app/cli.

Tokens

The CLI never sees your password. It uses tokens you mint on the Automation page, each doing exactly one job. A write token can only add files. A read token can only fetch them, and the server holds just a hash of it. Set them as environment variables; they last for the terminal window, so re-export after restarting it. Two commands use both at once: share, and serve when it mounts read-write.

Treat tokens like passwords. A token pasted anywhere public is burned: revoke it on the Automation page and mint a fresh one. Both token kinds take an optional limit per hour, day, week, month, or year of your choosing. A write token's limit is a number of uploads: a file of any size counts as one. A read token's limit is an amount of data served, in megabytes: fetching a 40 MB file spends 40 MB of it, listings are free, and a resumed download counts only the bytes actually sent. The tally resets when the chosen period turns, and read tokens keep a per-day history of what they served.

put

Uploads one file, encrypted on your device at any size up to about 900 GiB, or 500 MB on a free account, and a file over your limit is refused before a single byte is sealed or sent. Large files stream in parts, so nothing is ever held in memory whole, and several parts fly at once: --workers N anywhere on the line sets how many, three unless you say otherwise. --path files it into folders under the token's root, creating any that do not exist, up to eight levels deep. If the token allows links, the response includes a ready sharing link; the part after # is the key and never reaches the server. Sending the same unchanged file to the same folder twice says it is already in the vault instead of storing a duplicate; delete it in the app and the same command uploads it fresh.

A big upload that dies partway is not lost. Run the same command again and it resumes from the last part that made it, re-sending nothing: Ctrl-C, a dropped connection, or a closed laptop all end the same way, with the tool telling you to run it again. Parts already in flight finish sending first, so the resume count can be higher than the last line you saw. If the file itself changed in between, resuming would be wrong, so the tool says so and starts over. Progress lives in your temp folder, readable only by you, and is removed the moment the upload completes.

In a terminal, open printed links with open "url" in quotes or by copying them. Tapping a link in some terminal apps mangles the # and sends the key to the server; treat any link opened that way as burned.

One timing note: a file added from the CLI is readable by your read tokens at once, because the CLI wraps the key for them at upload. Its folder path, though, is filled in when you next open the app, so until then it lists at the top level. A file dropped by a simpler client, like a Shortcut, appears after that next open.

Passing - instead of a file reads standard input, spooled through a temporary file, so pipes work: pg_dump db | python3 quattle.py put - --name backup.sql. A name is required when reading a pipe. Long uploads report themselves part by part as they go.

ls

Lists everything the read token covers, with folder paths, sizes, dates, and ids. Names and paths are decrypted on your device; listings are free and do not count against a read limit. --path narrows the listing to one branch.

get and cat

get downloads and decrypts one file, then prints its SHA-256 so you can compare it with the checksum in the app's file menu. cat streams the decrypted bytes to standard output for piping. If the connection dies mid-download, get resumes from where it stopped, announcing itself; every chunk is authenticated, so a finished download cannot be silently wrong.

sync

Mirrors a local folder into the vault. It asks the server which files it already has, then uploads only what is new or changed, preserving your subfolder structure. Change detection is name, size, and modified time, so rerunning it is cheap and safe: unchanged files are skipped without uploading a byte. Files and folders whose names start with a dot are ignored.

This makes a nightly backup one line in a scheduled job. Interrupted runs are safe to repeat: every upload carries an idempotency key, so nothing is ever stored twice.

watch

Runs sync on a loop, every 60 seconds unless you say otherwise, until you stop it with Ctrl-C. Drop a file into the watched folder and it is in your vault within the interval.

rm

Deletes one file within the read token's scope. It lands in your trash like any other deletion, recoverable until the trash empties, and requires a read token with deleting turned on, which is off by default.

share

Mints a sharing link for a file already in the vault. The link behaves exactly like one minted at upload: the write token's configured lifetime and open settings apply, and the key rides in the part after #, which never reaches the server. This command uses both tokens: the read token finds and unlocks the file, the write token mints the link, and the file must sit inside the write token's folder.

verify

Proves a local folder matches the vault without downloading a byte. Every file's SHA-256 is computed locally and compared against the sealed checksum stored at upload, decrypted on your device. Files that differ or are missing from the vault are listed and the exit code is 1, so it slots straight into scheduled jobs.

restore

The mirror of sync: rebuilds the read token's files into a local folder, folder structure included, decrypting everything on your device. Files already present are skipped after their checksum matches the stored one, so rerunning fetches only what is missing or changed. --path restores just one branch, placed at the destination's root.

serve

Runs a WebDAV bridge on your own machine, so the vault mounts as a volume. With just the read token it is read-only: browse, open, copy out. Set the write token as well and it goes read-write: save into the mount, delete from it, make and fill folders, move and copy files, and it all lands sealed in the vault. Every byte is decrypted on your device as it is read and sealed on your device as it is written; the bridge listens on localhost only and stays up until Ctrl-C. Partial downloads work: Range requests decrypt only the chunks they need.

On a Mac the vault becomes a Finder volume: Go, Connect to Server, http://localhost:8787, Connect as Guest. Read-write it behaves like a disk: drag files in and they upload sealed, drag them to the Trash and they land in your quattle trash, make folders and fill them. Deleting and moving need a read token with deleting turned on. Two honest limits: renaming a folder is not supported, so move the files inside it instead, and an empty folder made through the mount lasts as long as the bridge runs, becoming permanent once a file lands in it. The hidden housekeeping files Finder writes are accepted and quietly discarded, so they never clutter the vault.

The bridge speaks the standard verbs: PROPFIND for listings, GET and HEAD with Range, and when writable PUT, DELETE, MKCOL, MOVE, COPY, LOCK and UNLOCK, so ordinary WebDAV clients work unmodified. That makes it the door for rclone, and with it most sync tooling: point a remote of type webdav at the bridge and rclone sync a folder both directions, rclone copy for one-way, rclone ls to look around. Files arrive as real, openable, shareable files in the vault, not opaque blobs. Files you save into folders through the bridge show up in the right place while it runs; if you restart it before next opening the app, they appear at the top level until that next open files them properly.

test and version

test re-runs the cryptographic self-check any time; it needs no network and no tokens. version prints the release, which you can match against the hash ledger. On slower devices, long uploads also announce each part as its encryption begins, so a working upload never looks stuck.

The tool seals and opens through the OpenSSL library your system already has, which uses the processor's own AES instructions: sealing runs at hundreds of megabytes per second. Where that library is not found, the built-in dependency-free implementation takes over automatically, slower but identical. test names the backend in use, and when the fast one is active it also proves the two produce the same bytes.

Machine output

Add --json anywhere on the line and ls, get, put, sync, test and version print one JSON document on standard output, progress chatter moves to standard error, and failures print {"error": "..."} with exit code 1. One format for every outcome, made for scripts, launchers, and anything that would rather parse than scrape.

git-annex

If you keep large files out of git with git-annex, quattle can be one of its remotes. The repository still tracks names and history; the file contents live in your vault, sealed on your machine before they leave it. Nothing about your annex is readable here, and a drop token can add content without being able to read any of it back.

Put quattle_annex.py beside quattle.py, make sure a program called git-annex-remote-quattle is on your PATH, then set up the remote once:

It uses both tokens: the drop token stores content, the read token fetches it and checks what is already there. The read token must cover the drop token's folder or something above it, or stored content will not be readable back. prefix chooses the folder inside that scope, and defaults to annex.

Dropping content from the remote sends it to your trash rather than destroying it, so a mistaken drop is recoverable until the trash empties. That requires a read token with deleting turned on, which is off by default.

Mount it in Finder

Start the bridge with both tokens set, then in Finder: Go, Connect to Server, http://localhost:8787, Connect as Guest. The vault mounts like a disk. Quick Look previews work, dragging files in uploads them sealed, dragging them to the Trash sends them to your quattle trash, and new folders are a right-click away. Copying out decrypts as fast as the disk can take it, and video plays straight off the mount, scrubbing included, because the bridge serves the exact byte ranges the player asks for.

Treat the mount as a place to move things in and out of and browse, not as a working directory. Apps that keep documents open, autosave in place, or save through temporary files belong on your disk: edit locally, then drag or sync the result in. The section at the bottom lists what that covers.

Keep it running

A launch agent starts the bridge when you log in and restarts it if it stops, which is what makes the mount and everything below feel like part of the machine. The tokens live in the agent's environment, so Finder, rclone, and anything else that uses the bridge never holds a credential of its own.

Swap in your own username in the two paths, paste your tokens, then load it once. It runs from the next login onward.

rclone

rclone speaks WebDAV, so one remote definition connects it to the bridge and the whole rclone toolbox follows. sync on a schedule is a nightly encrypted offsite backup whose contents are real files: openable in the viewer, shareable by link, restorable one at a time, not opaque pack blobs. copy moves things either direction without deleting anything, and check audits a folder against the vault without transferring a byte.

Deletes and moves through rclone need a read token with deleting turned on, and everything deleted lands in your quattle trash, so a mistaken sync flag is recoverable. bisync, rclone's two-way mode, does work against the bridge, but it is experimental on rclone's side and this one: keep it to folders you can afford to re-sync.

Skip rclone mount: it needs macFUSE and a system extension, and the Finder mount above already covers what it would give you.

Add it to your page

One import, no dependencies, nothing to build. Load it from here, or copy the file to your own site and verify it against the hash above; a copy you host updates only when you update it. Put your code in its own file rather than inline: sites with a strict security policy block inline scripts, and yours may be one of them.

Send a file

One call does everything. The file is sealed on the visitor's device in 4 MB chunks, uploaded in parts with live progress, and wrapped to your read tokens, so the app, the CLI, and your automations see it the moment it lands. When the token mints sharing links, the result carries one, and the part after # is the key, which never reaches the server.

Options: path files it into a folder inside the token's scope, name overrides the shown name, onProgress receives sentBytes and totalBytes, and base points the calls somewhere other than quattle.app, which the token section below puts to use.

Errors and repeats

Every failure throws with a plain sentence meant for people, so show it to your visitor as it is. A file over the account's size limit is refused before a single byte is sealed. Sending the same unchanged file to the same folder again comes back with repeated set and no link, and nothing is stored twice.

Your page's security policy

If your site sets a Content-Security-Policy, it needs two allowances: script-src for wherever quattle.js loads from, and connect-src https://quattle.app for the upload itself. A site with no policy needs nothing.

Prove the crypto

The module carries a self-test that runs the same known-answer vectors the app and the CLI are held to, in the visitor's own browser. Anyone can paste this into a console and watch the checks pass, which is the whole trust story in two lines.