bdb-deploy

Universal, config-driven build-and-deploy CLI. Build a project, rsync the output to a server over SSH, optionally restart a remote service and verify a healthcheck URL — all from one committed config file plus a local .env for secrets. Not tied to BDB infrastructure; works for any project.

Zero dependencies.

Install

npm install -D @hybridlabor-api/bdb-deploy

Setup (per project)

npx bdb-deploy init

Asks for build command, output directory, host, SSH user, key path, remote directory, optional restart command, optional healthcheck URL. Writes:

• bdb-deploy.json — safe to commit. Structure only, no secrets (uses ${VAR} placeholders).
• .env.example — safe to commit. Documents which env vars this project needs.
• .env — do not commit. Holds the real host/user/key path for your machine. Added to .gitignore automatically.

Multiple targets (e.g. staging + production)? Run init once, then copy the targets block in bdb-deploy.json and add a second ${VAR} set to .env.

Deploy

npx bdb-deploy --target production --dry-run   # see exactly what would happen, changes nothing
npx bdb-deploy --target production              # the real thing

If a target is configured with "production": true, you'll be asked to type the target name to confirm (skip with --yes, but only pass that when you mean it).

If there's only one target configured, --target is optional.

Config reference

{
  "version": 1,
  "build": {
    "command": "npm run build",
    "outputDir": "dist"
  },
  "targets": {
    "production": {
      "host": "${BDB_DEPLOY_PRODUCTION_HOST}",
      "user": "${BDB_DEPLOY_PRODUCTION_USER}",
      "sshKey": "${BDB_DEPLOY_PRODUCTION_SSH_KEY}",
      "remotePath": "/var/www/my-project/",
      "restartCommand": null,          // optional, runs over SSH after rsync
      "healthcheckUrl": null,          // optional, GET-checked after deploy
      "production": true               // requires typed confirmation unless --yes
    }
  }
}

${VAR} placeholders resolve from .env (loaded first) then the real process environment (which always wins — CI secrets override local .env).

What it actually does

1. Runs build.command in the repo root.
2. Hashes every file in build.outputDir (SHA-256 over path + content, sorted) and prints it — a record of exactly what's about to ship.
3. rsync -avz --delete the output directory to user@host:remotePath over SSH using the configured key. --delete means the remote directory ends up an exact mirror of the build output — files removed locally are removed remotely too.
4. If restartCommand is set, runs it over SSH after the sync.
5. If healthcheckUrl is set, GETs it and fails the whole run (non-zero exit) if the response isn't OK.

Skill

skills/bdb-deploy/SKILL.md is a thin wrapper for AI agents: it tells an agent when/how to invoke this CLI and to always dry-run first, but never lets the agent construct rsync/ssh commands by hand. Copy that directory into your agent skill setup if you want an agent to be able to trigger deploys safely.

Safety notes

• --delete on rsync is powerful — a wrong remotePath mirrors your build output onto the wrong directory and deletes whatever was there. Always --dry-run a new target before the first real run.
• SSH auth uses BatchMode=yes (fails immediately instead of hanging on a password prompt) and StrictHostKeyChecking=accept-new (trusts a host's key on first connection, then verifies it matches on every subsequent connection — protects against a changed host key later, doesn't protect against a malicious host on the very first connect).
• This tool never touches git. It doesn't commit, push, or care about your branch. Build-and-deploy only.