bdcli

bdcli is a Node.js CLI for project-local build and deploy workflows. It discovers deployment config from the current directory tree, runs a local build command, uploads artifacts over SSH/SFTP, and executes remote deployment commands.

This project is suitable for small teams and personal infrastructure where deployment is driven from the application repository. The current release should be treated as early-stage software.

Installation

npm install -g bdcli-deploy
bdcli --help

For one-off usage without a global install:

npx bdcli-deploy --help

Requirements

• Node.js 20 or newer
• A local project that can be built from a shell command such as npm run build
• SSH access to the target host
• A remote Unix-like environment with mkdir, find, rm, tar, and /tmp

Supported environments

• Local machine: intended for macOS, Linux, and Windows with Node.js
• Remote machine: intended for Linux or other Unix-like servers

bdcli normalizes remote paths as POSIX paths and uses Unix shell commands on the server, so Windows targets are not supported.

Quick start

bdcli init --with-local
bdcli doctor --env staging
bdcli build
bdcli deploy staging --dry-run
bdcli deploy staging

Commands

bdcli init
bdcli init --with-local
bdcli build
bdcli build --target weapp
bdcli build --no-pack
bdcli build --pack-name my-bundle
bdcli doctor
bdcli doctor --env production
bdcli deploy
bdcli deploy staging
bdcli deploy production --dry-run
bdcli deploy production --skip-build
bdcli deploy production --target weapp

Config files

• /.deploy.config.json: required primary config, safe to commit
• /.deploy.local.json: optional local override config, intended for machine-local secrets and paths

Merge rules:

• objects: deep merge
• arrays: override completely
• scalar values: local overrides primary

/.deploy.local.json should stay out of version control.

Config example

{
  "version": 1,
  "project": "my-app",
  "build": {
    "command": "npm run build",
    "output": "dist",
    "cleanOutput": false,
    "pack": {
      "enabled": true,
      "name": "my-app"
    }
  },
  "deploy": {
    "strategy": "upload",
    "uploadMode": "archive",
    "cleanRemoteBeforeUpload": false,
    "gitVersionInfo": {
      "enabled": true,
      "filename": "._gitVersionInfo"
    }
  },
  "environments": {
    "staging": {
      "enable": true,
      "remotePath": "/var/www/my-app-staging",
      "beforeUpload": [
        "mkdir -p /var/www/my-app-staging"
      ],
      "afterUpload": [
        "echo deployment complete"
      ]
    },
    "production": {
      "enable": false,
      "remotePath": "/var/www/my-app",
      "beforeUpload": [
        "mkdir -p /var/www/my-app"
      ],
      "afterUpload": [
        "pm2 reload my-app"
      ]
    }
  }
}

Optional local override:

{
  "environments": {
    "staging": {
      "host": "127.0.0.1",
      "port": 22,
      "username": "deploy",
      "privateKey": "C:/Users/your-name/.ssh/id_rsa"
    },
    "production": {
      "host": "127.0.0.1",
      "port": 22,
      "username": "deploy",
      "privateKey": "C:/Users/your-name/.ssh/id_rsa"
    }
  }
}

build may also be an array of build configurations. With multiple entries, each item must have a unique name; bdcli build / bdcli deploy then prompt interactively for the target, or take it from --target <name>:

{
  "build": [
    { "name": "h5", "command": "npm run build:h5", "output": "dist-h5" },
    { "name": "weapp", "command": "npm run build:weapp", "output": "dist-weapp" }
  ]
}

Config fields

• version: config version for future compatibility
• project: project name used in logs
• build: a single build object, or an array of build objects
• build.name: optional identifier; required and unique on each item when build is an array with multiple entries
• build.command: local shell command for building the project
• build.output: local artifact directory whose contents are deployed
• build.cleanOutput: clear the contents of build.output before running the build command, default false
• build.pack.enabled: pack the build output into a zip archive after bdcli build, default true
• build.pack.name: pack archive file name, default <project>[-<build.name>].zip; the archive is written into build.output
• deploy.strategy: currently only upload
• deploy.uploadMode: archive or direct, default archive
• deploy.cleanRemoteBeforeUpload: clear target directory contents before upload
• deploy.gitVersionInfo.enabled: inject git version metadata into build output before upload, default true
• deploy.gitVersionInfo.filename: metadata file name written into build.output, default ._gitVersionInfo
• environments.<name>.enable: when false, deployment is blocked
• environments.<name>.host: SSH host
• environments.<name>.port: SSH port, default 22
• environments.<name>.username: SSH username
• environments.<name>.password: optional password auth
• environments.<name>.privateKey: optional path to private key file
• environments.<name>.passphrase: optional key passphrase
• environments.<name>.remotePath: remote upload directory
• environments.<name>.beforeUpload: remote commands before upload
• environments.<name>.afterUpload: remote commands after upload

Behavior notes

• bdcli deploy deploys all enabled environments sequentially in config order and skips environments with enable: false
• bdcli deploy <env> fails when enable is false
• when build has multiple entries, bdcli build and bdcli deploy ask which one to use; pass --target <name> to skip the prompt (required in non-interactive environments such as CI, and honored together with --skip-build to pick the artifact source)
• deploy uploads and extracts the contents inside build.output, not the outer directory itself
• bdcli never clears build.output on its own unless build.cleanOutput is true; when enabled, the directory contents (not the directory itself) are removed before the build command runs, and only paths strictly inside the project root are accepted — the project root itself and paths outside it are refused
• bdcli build writes git version info into build.output first, then packs the output contents (including that file) into a zip stored inside build.output; use --no-pack or build.pack.enabled: false to skip
• when uploadMode is archive, deploy excludes the pack zip produced by bdcli build from the uploaded archive so artifacts are not transferred twice
• with uploadMode: direct the pack zip is uploaded along with everything else in build.output; directory upload has no per-file filtering, so keep pack disabled if that extra transfer matters
• clean mode refuses / and remote paths shallower than 3 levels, and clears contents instead of deleting the directory itself
• bdcli doctor validates config and attempts an SSH connection for enabled environments
• bdcli init --with-local creates both config files
• config discovery walks upward from the current working directory until it finds /.deploy.config.json

Security notes

• Prefer privateKey authentication over password whenever possible
• Keep /.deploy.local.json untracked; it may contain secrets or workstation-specific key paths
• beforeUpload and afterUpload run as remote shell commands; treat them as privileged operations
• When git version info injection is enabled, bdcli writes a metadata file into build.output after build and before upload
• The default metadata file name is ._gitVersionInfo; if your web server exposes dot-underscore files, add a rule to block external access or change the filename

Development

npm test
npm run lint
npm pack --dry-run