About

tagbackup is a single-binary CLI tool that uploads, downloads, lists, and deletes files on any S3-compatible bucket — with files identified and filtered by simple human-readable tags baked directly into the object key. No external index. No database. No telemetry.

These are human-readable tags embedded in the object key — not AWS S3 object tags. No separate tag API, no index to keep in sync. Tags travel with the file, not beside it. Combine them with AND, OR, and NOT expressions to pull exactly the files you need.

---

What it is (and isn't)

tagbackup is for tagged single-file dumps and restores on any S3-compatible bucket — think pg_dump → push → pull --latest on a laptop.

It is not a full encrypted backup suite like restic, and not a sync tool like rclone. Credentials stay on your machine; there is no hosted service.

---

Demo

$ tagbackup push dump.sql --bucket=dbbackup --tag=nightly,prod
✓ Uploaded 1776831788343-nightly,prod-dump.sql

$ tagbackup files --bucket=dbbackup --tag=nightly
TIMESTAMP                 SIZE     FILENAME  TAGS
2026-06-13 22:34:01Z    1.2 MiB   dump.sql  [nightly, prod]
2026-06-08 22:34:01Z    1.1 MiB   dump.sql  [nightly, prod]

$ tagbackup pull --bucket=dbbackup --tag=nightly+prod --latest
✓ Downloaded dump.sql

Run tagbackup serve to get a local web UI for browsing, filtering, uploading, and deleting — bound to 127.0.0.1 only. Use Refresh to re-list the bucket if files change outside the UI.

---

Installation

Linux / macOS (one-liner):

curl -sfL https://tagbackup.com/install.sh | sh

Or download a binary directly from GitHub Releases:

Extract the archive, make the binary executable, and move it onto your PATH. See the documentation for more detail.

Upgrading: on Linux/macOS, re-run the one-liner above. On Windows, download the latest release and replace tagbackup.exe. Config and bucket aliases are unchanged.

---

Quick Start

# 1. Add a bucket (interactive setup)
tagbackup bucket add

# 2. Push a file with tags
tagbackup push dump.sql --bucket=dbbackup --tag=nightly,prod

# 3. List files by tag
tagbackup files --bucket=dbbackup --tag=prod

# 4. Pull the latest matching file
tagbackup pull --bucket=dbbackup --tag=nightly+prod --latest

See the documentation for all flags and options.

---

Commands

---

Features

• Tag-based organization — tags are embedded in the S3 object key; filter with AND / OR / NOT expressions, no external index needed.
• Any S3-compatible store — works with AWS S3, Cloudflare R2, MinIO, Backblaze B2, and any provider that speaks the S3 API.
• Local web UI — run tagbackup serve to browse and manage buckets from your browser; binds to 127.0.0.1 only.
• Scriptable — non-interactive mode, JSON output (--json), and meaningful exit codes make it easy to use in cron jobs and shell scripts.
• Flexible credentials — static keys, AWS profiles, IAM roles, or environment variables; resolution order is predictable and documented.
• Atomic downloads — writes to a temp file and renames on success; an interrupted download never leaves a partial file.
• No telemetry — all API calls go directly between tagbackup and your bucket; nothing dials home.

---

Tag Expressions

Used with pull, files, and delete via the --tag flag (optional for files: omit it to list every file).

tagbackup files --bucket=mybackup --tag=prod             # tagged prod
tagbackup files --bucket=mybackup --tag=db+prod          # both db and prod
tagbackup delete --bucket=mybackup --tag=nightly+prod --older-than=30d --force

---

Classic Use Case

Cron pushes it nightly. Your laptop pulls the latest whenever you need it.

# On the server (cron)
pg_dump mydb | tagbackup push - --bucket=db --tag=nightly,prod --filename=dump.sql
tagbackup delete --bucket=db --tag=nightly+prod --older-than=30d --force

# On your laptop
tagbackup pull --bucket=db --tag=nightly+prod --latest

---

Contributing

Contributions, bug reports, and feature requests are welcome. Please open an issue or submit a pull request.

---

License

MIT · tagbackup.com