https://github.com/zz-drop/zz-drop
Minimalist CLI for one-shot file transfer to a configured cloud destination. Nextcloud, Google Drive, OneDrive, Dropbox.
https://github.com/zz-drop/zz-drop
argon2 cli cloud-storage dropbox e2e-encryption e2ee google-drive nextcloud oauth onedrive ratatui rust tui webdav xchacha20
Last synced: about 1 month ago
JSON representation
Minimalist CLI for one-shot file transfer to a configured cloud destination. Nextcloud, Google Drive, OneDrive, Dropbox.
- Host: GitHub
- URL: https://github.com/zz-drop/zz-drop
- Owner: zz-drop
- License: apache-2.0
- Created: 2026-04-25T18:34:58.000Z (about 2 months ago)
- Default Branch: main
- Last Pushed: 2026-05-12T20:17:16.000Z (about 1 month ago)
- Last Synced: 2026-05-12T20:26:54.098Z (about 1 month ago)
- Topics: argon2, cli, cloud-storage, dropbox, e2e-encryption, e2ee, google-drive, nextcloud, oauth, onedrive, ratatui, rust, tui, webdav, xchacha20
- Language: Rust
- Homepage: https://zz-drop.net
- Size: 633 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE-APACHE
- Security: SECURITY.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
# zz-drop
[](https://github.com/zz-drop/zz-drop/actions/workflows/build.yml)
[](https://github.com/zz-drop/zz-drop/releases)
[](#license)
Minimalist CLI to put files into — and get files from — a
configured safe cloud destination. Four providers, one command,
end-to-end encryption on every credential the tool stores.
zz-drop is **not** a sync tool, **not** a mount tool, **not** a
generic cloud file manager. One-shot uploads, one-shot downloads,
explicit, fast.
## Install
```bash
# macOS — Homebrew tap (preferred). Installs `zz-drop` + `zz-tui`,
# wires bash/zsh/fish completions, links `zz` to `zz-drop` if free.
brew install zz-drop/zz-drop/zz-drop
# Linux & WSL — signed binaries via curl-installer (preferred).
# Also works on macOS if you prefer no package manager.
curl -fsSL https://github.com/zz-drop/zz-drop/releases/latest/download/zz-drop-installer.sh | sh
```
No install path needs root.
Every release artifact is signed with [minisign](https://jedisct1.github.io/minisign/);
the public key is [`release-key.pub`](release-key.pub).
Build from source: see [`docs/build.md`](docs/build.md).
## Quickstart
```bash
zz c # one-off setup (configuration TUI)
zz file.md # upload
zz d file.md # download
zz z # unlock the agent for the session
zz q # lock the agent
```
```text
$ zz readme.md
uploaded readme.md 12 KiB → casa-nc · cloud.example.org/zz-drop
$ zz d leggimi.txt
downloaded leggimi.txt 34 KiB ← casa-nc · cloud.example.org/zz-drop
```
Output always names the active alias and the destination. Sizes
are binary (`KiB` / `MiB` / `GiB`). Colors only on a TTY, with
`NO_COLOR` / `CLICOLOR=0` honored.
## What you get
- **Four destinations**: Nextcloud (WebDAV), Google Drive
(OAuth device flow), OneDrive (OAuth device flow + Microsoft
Graph), Dropbox (OAuth paste-code + PKCE, App folder).
- **Encrypted profile container** (`profile-local.zz`):
XChaCha20-Poly1305 + Argon2id; passphrase never leaves the
device. The server side (when used in v2) sees only an
opaque encrypted blob.
- **Local per-user agent** in the same binary: holds the
decrypted profile in RAM only, TTL 10 min, idle locked-exit
after 5 min, Unix socket bound per-UID.
- **Composable verb grammar** for power users:
`zz sx file.md` (zstd compress), `zz sa dir/` (bulk
top-level), `zz sar dir/` (recursive), `zz sarx dir/`
(recursive + tar.zst). The `d` family mirrors it.
## TAB completion that knows your state
`zz` ships its own shell completion — SACS, state-aware
contextual suggestions. It doesn't just list verbs: it asks the
local agent for the *actual* state of your data and ranks
candidates accordingly.
`zz d ` shows remote files; `zz z ` shows the inner
profiles inside your unlocked container; `zz s ` falls
back to the local filesystem like every other CLI.
The script itself is tiny (~30 lines per shell); the brain is
the `zz` binary, so rebuilding the tool updates the suggestions
— the script never changes. zsh styling (group headers, menu
select, filename colors) is opt-in via six lines in `~/.zshrc`,
scoped to `zz` only so it leaves `git`, `ls`, `cd`'s TAB
behaviour untouched.
Brew install handles this for you. Manual install (other paths,
or to override):
```bash
zz --completions bash | source
zz --completions zsh > ~/.zfunc/_zz # then `compinit`
zz --completions fish > ~/.config/fish/completions/zz.fish
```
Full installation guide, zsh styling block and the
download-glob wrapper for `zz d 'Q*'`:
[`docs/sacs.md`](docs/sacs.md).
## TUI
The configuration TUI is a separate binary, `zz-tui`, shipped
in the same release tarball as `zz-drop`. `zz c` exec's it.
Use the TUI to:
- onboard a cloud destination (provider OAuth, Nextcloud Login
Flow, or Nextcloud app-password)
- set or rotate the master passphrase
- add / remove inner profiles inside the container
- run diagnostics
The TUI is **setup-only**. Daily file moves stay in the CLI.
## Scope (v1)
In: explicit one-shot upload / download, one configured cloud
target per profile, the local agent, the configuration TUI.
Out: file sync, mount-as-FS, public share links, generic remote
file manager, team / org access.
The next features in flight are listed in the [project
roadmap](https://github.com/zz-drop).
## Documentation
- [`COMMANDS.md`](COMMANDS.md) — every command, examples,
exit codes, parser rule
- [`SECURITY.md`](SECURITY.md) — threat model, server-side
guarantees and non-claims, supported crypto
- [`docs/build.md`](docs/build.md) — build from source, BYO
OAuth client IDs, shell completion install
- [`docs/agent.md`](docs/agent.md) — agent protocol, socket
layout, token handshake, lock / TTL semantics
- [`docs/sacs.md`](docs/sacs.md) — state-aware completion
internals
- [`docs/profile-format.md`](docs/profile-format.md) —
`profile.zz` envelope and payload schema
- [`docs/providers/`](docs/providers/) — per-provider notes
(Nextcloud, Google Drive, OneDrive, Dropbox)
## License
Dual: [MIT](LICENSE-MIT) OR [Apache-2.0](LICENSE-APACHE) at your
option.