CLI

@s3nd/cli is its own package, built on s3nd as a primitive — so nothing a command line needs ships to your server.

npm install -g @s3nd/cli
s3nd setup
s3nd put ./report.pdf

setup asks where transfers are stored, the bucket and the keys, saves them for this machine and checks the bucket works. Every command then works from any directory. Without installing anything, npx @s3nd/cli setup does the same.

It has no dependencies of its own beyond s3nd: node:util's parseArgs is the whole argument parser.

setup and init

setup asks where transfers are stored (a list you move through with the arrow keys), the bucket and the keys, one question at a time, with where to find each value. It writes ~/.config/s3nd/config.json, readable by you only and used from any directory, then checks the bucket live. The provider list, while it is open:

? Where should transfers be stored?
  AWS S3
❯ Cloudflare R2                  no egress fees
  Scaleway
  Wasabi
  MinIO                          on this machine or self-hosted
  Another S3-compatible service  Backblaze B2, DigitalOcean Spaces, Hetzner…
  A s3nd server                  someone else runs it; you only need its URL
  ↑↓ to move · Enter to pick

Once picked it folds into one line, and the whole run reads:

$ s3nd setup
Set up s3nd on this machine
Saved to ~/.config/s3nd/config.json, used from any directory. Ctrl+C leaves without writing.

? Where should transfers be stored? Cloudflare R2
  Dashboard → R2 → Overview, "Account ID" in the side panel. The S3 API URL works too.
? Cloudflare account ID 8c4f…
  An existing bucket. The check at the end tells you if it is not reachable.
? Bucket name transfers
  R2 → Manage API tokens → Create API token, with Object Read & Write on this bucket.
? Access key ID 5d1e…1a2b
? Secret access key (hidden) ••••••••••••••••

✓ Saved ~/.config/s3nd/config.json (readable by you only)
  Cloudflare R2 · bucket "transfers" · credentials: key …1a2b

Checking it works…
✓ Configuration: bucket "transfers", region "auto", endpoint https://8c4f….r2.cloudflarestorage.com
✓ Credentials: resolved, key ends in 1a2b
✓ Bucket reachable: HeadBucket succeeded
✓ Write, read, delete: round-tripped a probe object
! Expiry cleanup: no lifecycle configuration
  → Add an S3 lifecycle rule that expires objects under "transfers/" after a day or two.

Ready. Send something:
  s3nd put ./a-file

init asks the same questions for a project instead: it writes ./s3nd.config.json, meant to be committed, with ${…} references to the keys, and the keys themselves in a .env beside it. It warns when no .gitignore there lists .env.

A flag answers its question in advance: --provider (aws, r2, scaleway, wasabi, minio, other or remote), --bucket, --region, --endpoint, --remote. An existing file is only replaced once you say so, or with --force. Ctrl+C leaves without writing anything.

Nobody at the keyboard (a pipe, CI, or --yes), nothing is asked: the flags write a starter with ${…} references, and a missing --bucket is an error rather than a placeholder.

s3nd init --yes --provider r2 --bucket transfers

You rarely need to type setup at all. Any command that needs a bucket, run on a machine with none configured, offers to set one up on the spot and then carries on with what you asked for.

Without a server follows the R2 one end to end.

doctor

The check setup ends with, on demand. S3 misconfiguration fails late and vaguely — a policy that looks right, credentials that resolve to nothing, a region the endpoint disagrees with. doctor turns all of that into a list:

$ s3nd doctor
Using /home/you/transfers/s3nd.config.json
✓ Configuration: bucket "transfers", region "eu-west-3"
✓ Credentials: resolved, key ends in 1234
✓ Bucket reachable: HeadBucket succeeded
✓ Write, read, delete: round-tripped a probe object
! Expiry cleanup: no enabled expiration rule
  → Add an S3 lifecycle rule that expires objects under this bucket after a day or
    two. Without it, expired transfers stay stored and billed.

1 check(s) failed.

It does not read your policy and reason about it; it performs the three operations s3nd needs and reports what actually happened. The probe object is deleted before it returns.

That last check is the one that earns the command. expiresIn stops a transfer being handed over; only a lifecycle rule deletes the object. Nothing surfaces the gap until a bill does.

Pointed at a server, doctor checks the only thing that matters there — a real round trip:

$ s3nd doctor --remote https://drop.example.com/api/transfers --token "$TOKEN"
✓ Server: https://drop.example.com/api/transfers answered
✓ Create, read, delete: round-tripped code 8WTXQC8R

put, get, rm

$ s3nd put ./report.pdf
report.pdf · 284 kB · expires in 1 hour
K7QP2M4X

The code goes to stdout and everything else to stderr, so it composes:

CODE=$(s3nd put ./report.pdf)

put - reads stdin instead, which is how a directory or a database dump travels:

tar cz ./project | s3nd put - --name project.tar.gz
pg_dump notes | gzip | s3nd put - --name notes.sql.gz --expires-in 7d

On the other machine:

$ s3nd get K7QP2M4X
Wrote /home/you/report.pdf · 284 kB

$ s3nd rm K7QP2M4X
Burned K7QP2M4X

get writes to the stored filename unless you pass -o; -o - sends the payload to stdout. A code holding a snapshot rather than a file prints its JSON instead.

config

What the CLI resolved, and — the part that ends most confusions — where each value came from:

$ s3nd config
file         /home/you/transfers/s3nd.config.json (profile "r2")
profiles     r2, local
mode         straight to S3

bucket       transfers                                 $S3ND_BUCKET
region       auto                                      s3nd.config.json (r2)
endpoint     https://8c4….r2.cloudflarestorage.com     s3nd.config.json (r2)
prefix       drops                                     --prefix
credentials  …1a2b                                     s3nd.config.json (r2)
expires in   1 day                                     s3nd.config.json (r2)

It never prints a secret: the access key id is masked to its last four characters, and the secret and the bearer token are only ever reported as set. It reads no credentials and touches no bucket, so it works before anything else does.

The configuration file

Everything the flags take, in a file the CLI finds by itself:

{
  "bucket": "transfers",
  "region": "auto",
  "endpoint": "https://${R2_ACCOUNT_ID}.r2.cloudflarestorage.com",
  "prefix": "transfers",
  "expiresIn": "24h",
  "envFile": ".env",
  "credentials": {
    "accessKeyId": "${R2_ACCESS_KEY_ID}",
    "secretAccessKey": "${R2_SECRET_ACCESS_KEY}"
  }
}

Anything else is rejected by name, with the key it was probably meant to be:

$ s3nd config
Unknown key "buckett" in /home/you/transfers/s3nd.config.json. Did you mean "bucket"?

Where it is looked for

1. --config <path>, or $S3ND_CONFIG. An explicit path that is not there is an error, never a silent fallback.
2. s3nd.config.json, .s3ndrc.json or .s3ndrc, from the working directory upwards — so a config beside the project is found from any directory inside it.
3. ~/.config/s3nd/config.json (or $XDG_CONFIG_HOME/s3nd/config.json), for the machine-wide one.

The first file found wins outright. Two files being merged is the kind of thing nobody can debug from the outside.

Secrets stay outside it

${VAR} in any string is read from the environment, and envFile names a file to load first — without overwriting anything the shell already set, so an exported variable stays the last word. A missing one is reported by name before any request is made:

$ s3nd put ./report.pdf
"endpoint" in /home/you/transfers/s3nd.config.json references ${R2_ACCOUNT_ID}, which is not set.
Set it in /home/you/transfers/.env, or export it before running s3nd.

So the file is committable and the keys are not. An env file the config merely declares may be missing — the variables can just as well be exported — while one passed as --env-file must exist.

Profiles

One file, several setups, chosen with -p or $S3ND_PROFILE:

{
  "bucket": "transfers",
  "prefix": "drops",
  "profiles": {
    "prod": { "remote": "https://drop.example.com/api/transfers", "token": "${S3ND_TOKEN}" },
    "local": {
      "endpoint": "http://localhost:9000",
      "credentials": { "accessKeyId": "minioadmin", "secretAccessKey": "minioadmin" }
    }
  }
}

s3nd -p local doctor
s3nd -p prod put ./report.pdf

A profile overrides the root key by key, credentials included as one unit: half a key pair, inherited from two places, is not something anyone means to configure.

What beats what

A flag beats an environment variable, which beats the configuration file, which beats the default. s3nd config prints the winner of each.

Credentials have no flag on purpose: a secret in an argument is a secret in ps and in your shell history. Put them in the environment, in an env file, or leave them to the AWS provider chain — a profile, an instance role, an SSO session.

Against your own server

Every command takes --remote, which points it at a deployment of the transfer protocol instead of at S3:

s3nd --remote https://drop.example.com/api/transfers put ./report.pdf

This is not a second implementation. The CLI has exactly one — the protocol client — wired either to fetch or, without --remote, straight into the handler in the same process. The two modes cannot drift apart, because there is only one of them.

The practical consequence: your laptop needs no S3 credentials. It holds a token for your own deployment, which holds the credentials. Setting up a server is that side of it.

Options