CLI¶
buckethead is a small Typer + Rich command that reads credentials from
the same env vars as BucketHeadSettings — all prefixed BUCKETHEAD_
with __ as the nesting delimiter:
BUCKETHEAD_BUCKET__NAME, BUCKETHEAD_BUCKET__ACCESS_KEY_ID,
BUCKETHEAD_BUCKET__SECRET_ACCESS_KEY, plus optional
BUCKETHEAD_BUCKET__ENDPOINT_URL or BUCKETHEAD_CLOUDFLARE__ACCOUNT_ID,
BUCKETHEAD_SNAPSHOT__KEY, BUCKETHEAD_SNAPSHOT__BRANCH.
Per-user state (env overrides, project → bucket mappings, share-bucket
attachments) lives in ~/.config/buckethead/config.toml; see
buckethead config below.
Every sub-command accepts --help for its full flag list — this page
covers what each command is for rather than enumerating options.
Status and snapshot commands¶
buckethead status¶
Non-destructive probe. Checks connectivity to the bucket, reports the current snapshot key, size, and mtime, and does not start the in-memory DB. Safe to run from a cron.
buckethead inspect¶
Download the current-branch snapshot into a temp file, open it locally, and print schema + row counts per table.
$ buckethead inspect
snapshot: my-bucket/bucketsqlite/snap.db
┏━━━━━━━━━━━┳━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ table ┃ rows ┃ columns ┃
┡━━━━━━━━━━━╇━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ bh_kv │ 42 │ key, value, created_at, updated_at │
│ filestore │ 7 │ bh_key, object_key, size, mime, filename... │
│ kv │ 7 │ k, v │
└───────────┴──────┴─────────────────────────────────────────────┘
buckethead restore <dest>¶
Download the snapshot to a local path (no in-memory hydration).
FileStore commands¶
buckethead files list¶
Paginated listing of filestore entries.
buckethead files get <bh-key> <dest>¶
Download one blob by its content-hash bh-key.
buckethead files gc¶
Reconcile the filestore: delete R2 objects that have no SQLite row, respecting a grace window to avoid racing in-flight puts.
$ buckethead files gc --dry-run # what would happen?
$ buckethead files gc --grace-seconds 300 # actually clean up
Sharing¶
Requires a share bucket provisioned via buckethead provision
share-bucket (below). Credentials live in the configured secret store
and the share bucket layout is read from
~/.config/buckethead/config.toml — keyed by --project. No
share-specific env vars.
Library callers get the same composition via
ShareConfig.from_project("<name>") or, more directly,
BucketSQLite(project="<name>") — see the
sharing API reference.
buckethead shares share¶
Copy a FileStore blob into the project's share bucket and print its
URL. Required: <bh-key> argument, --project <name>. In public
mode the URL is the public base URL + share key; in protected mode
it's a presigned GET. --ttl-days 0 skips expiry (public mode only);
--name overrides the URL slug.
buckethead shares list¶
List every active share for a project. Required: --project <name>.
buckethead shares revoke¶
Revoke a share by share-key or bh-key. Required: <key> argument,
--project <name>. Pass --all when a bh-key matches multiple
shares.
buckethead shares sweep¶
Delete expired shares from the bucket + DB. Required: --project <name>.
Provisioning¶
One-time setup. Creates buckets, issues credentials, stores them in
the secret store (1Password by default), and updates
~/.config/buckethead/config.toml. All provisioning commands accept
--cloud / --secret-store overrides — defaults come from
BUCKETHEAD_CLOUD (default cloudflare-r2) and
BUCKETHEAD_SECRET_STORE (default 1password).
buckethead provision bucket¶
Create a primary R2 bucket and store scoped credentials. Required:
--project <name>. If --bucket-name is omitted, the user config
persists a stable auto-generated name per project.
buckethead provision register¶
Store pre-existing S3 credentials in the secret store without making
any cloud calls. Useful when a bucket already exists. Required:
--project <name>.
buckethead provision destroy¶
Revoke the token, delete the bucket, remove the 1Password item, and
drop the config entry. Required: --project <name>.
buckethead provision share-bucket¶
Provision a separate share bucket for a project's file sharing.
Required: --project <name>. Sets the share / share_mode /
share_public_base_url fields on the project entry in
~/.config/buckethead/config.toml so the shares
subcommands can find it.
buckethead provision share-bucket-destroy¶
Tear down the share bucket for a project. Leaves the primary intact.
Required: --project <name>.
User config¶
Inspect per-user config without opening an editor.
buckethead config path¶
Print the absolute path to the config file (XDG-respecting, defaults
to ~/.config/buckethead/config.toml).
buckethead config show¶
Print the contents, or a placeholder if the file doesn't exist yet.
Benchmarking and stress¶
buckethead bench list / buckethead bench run <preset>¶
Benchmark BucketHead's KV layer — latency, throughput, YCSB, and
flush-impact suites. Runs against a real bucket and writes artifacts
under a run directory. buckethead bench report <run-dir> re-renders
the HTML report from existing artifacts.
bh-stress — stress harness¶
The stress harness ships as a sibling package (src/stress/) that
consumes BucketHead through its public library API — it is not part
of the buckethead CLI. The bh-stress console script is installed
alongside buckethead; invoke it via:
bh-stress list— enumerate presetsbh-stress estimate <scenario>— R2 cost projection onlybh-stress run <scenario> [--project NAME]— execute end-to-endbh-stress report <run-dir>— (re)render index.html
run resolves its bucket config the same way a library consumer
would: BucketSQLite() pulls from BUCKETHEAD_* env or, with
--project, from the named project in ~/.config/buckethead/config.toml.