Building the CLI

Build commands, packaging, and binary distribution for the Bitwarden CLI

The Bitwarden CLI can be built from source for development or custom distribution. The build system supports both OSS (open-source) and commercial (Bit) builds.

Prerequisites

• Node.js runtime (latest LTS version recommended)
• npm package manager
• pkg for creating native executables

Development Builds

OSS Build (Open Source)

Build the open-source version of the CLI:

# Standard build
npm run build:oss

# Production build (optimized)
npm run build:oss:prod

# Watch mode (rebuilds on file changes)
npm run build:oss:watch

The output is placed in build/bw.js.

Debug Mode

Run with Node.js inspector for debugging:

# Build and debug
npm run build:oss:debug

# Or debug existing build
npm run debug

Attach a debugger to the running process on the default inspector port.

Commercial Build

Build the commercial version (requires Bitwarden license files):

# Standard build
npm run build:bit

# Production build
npm run build:bit:prod

# Watch mode
npm run build:bit:watch

Binary Distribution

Platform-Specific Packaging

The CLI uses pkg to create standalone native executables:

Windows (x64)

# OSS build
npm run dist:oss:win

# Commercial build
npm run dist:bit:win

Output: dist/oss/windows/bw.exe or dist/bit/windows/bw.exe

macOS (Intel)

# OSS build
npm run dist:oss:mac

# Commercial build
npm run dist:bit:mac

Output: dist/oss/macos/bw or dist/bit/macos/bw

macOS (ARM64)

# OSS build
npm run dist:oss:mac-arm64

# Commercial build
npm run dist:bit:mac-arm64

Output: dist/oss/macos-arm64/bw or dist/bit/macos-arm64/bw

Linux (x64)

# OSS build
npm run dist:oss:lin

# Commercial build
npm run dist:bit:lin

Output: dist/oss/linux/bw or dist/bit/linux/bw

Linux (ARM64)

# OSS build
npm run dist:oss:lin-arm64

# Commercial build
npm run dist:bit:lin-arm64

Output: dist/oss/linux-arm64/bw or dist/bit/linux-arm64/bw

Packaging Process

Each distribution command follows this workflow:

1. Build: Compile TypeScript to JavaScript with webpack
2. Clean: Remove previous distribution files
3. Package: Create native executable with pkg

For example, npm run dist:oss:win executes:

npm run build:oss:prod  # Build with production optimizations
npm run clean            # Remove old dist files
npm run package:oss:win  # Create Windows executable

Direct Packaging

To package an existing build without rebuilding:

# Windows
npm run package:oss:win

# macOS (Intel)
npm run package:oss:mac

# macOS (ARM64)
npm run package:oss:mac-arm64

# Linux (x64)
npm run package:oss:lin

# Linux (ARM64)
npm run package:oss:lin-arm64

Package Configuration

The package.json defines the pkg configuration:

{
  "bin": {
    "bw": "build/bw.js"
  },
  "pkg": {
    "assets": [
      "./build/**/*"
    ]
  }
}

Pkg Targets

The build system targets these platforms:

• win-x64: Windows x64
• macos-x64: macOS Intel
• macos-arm64: macOS Apple Silicon
• linux-x64: Linux x64
• linux-arm64: Linux ARM64

All bundled assets from ./build/**/* are included in the executable.

Build System

Webpack Configuration

Builds use webpack for bundling:

• OSS: Default webpack configuration
• Commercial: Custom configuration at ../../bitwarden_license/bit-cli/webpack.config.js

Production Mode

Production builds set NODE_ENV=production for optimizations:

cross-env NODE_ENV=production webpack

Optimizations include:

• Tree shaking
• Minification
• Dead code elimination

Testing

Run tests before building:

# Run all tests
npm test

# Watch mode
npm run test:watch

# Watch all tests
npm run test:watch:all

Publishing to NPM

Publish the OSS version to npm:

npm run publish:npm

This command:

1. Builds with production optimizations
2. Publishes to npm with public access

Only authorized maintainers should publish to npm.

Directory Structure

apps/cli/
├── build/              # Compiled JavaScript output
│   └── bw.js          # Main CLI entry point
├── dist/              # Platform-specific binaries
│   ├── oss/
│   │   ├── windows/
│   │   ├── macos/
│   │   ├── macos-arm64/
│   │   ├── linux/
│   │   └── linux-arm64/
│   └── bit/           # Commercial builds
├── src/               # TypeScript source code
│   ├── bw.ts         # Entry point
│   ├── program.ts    # Core commands
│   ├── vault.program.ts
│   ├── serve.program.ts
│   └── ...
└── package.json

Common Issues

Build Failures

TypeScript errors: Ensure you’re using a compatible Node.js version

node --version  # Should be latest LTS

Missing dependencies: Clean install

rm -rf node_modules package-lock.json
npm install

Packaging Failures

pkg not found: Install globally

npm install -g pkg

Asset bundling issues: Verify the build output exists

ls -la build/bw.js

Custom Builds

To create a custom build for specific requirements:

1. Modify source: Make changes to TypeScript files in src/
2. Build: Run npm run build:oss or npm run build:oss:prod
3. Test: Run the built CLI with node build/bw.js
4. Package: Create executables for your target platforms

Example: Custom Command

Add a custom command in src/program.ts:

program
  .command("custom")
  .description("My custom command")
  .action(async () => {
    // Your custom logic
    const response = Response.success("Custom command executed!");
    this.processResponse(response);
  });

Build and test:

npm run build:oss
node build/bw.js custom

Next Steps

Commands Reference

Learn about all available CLI commands

Contributing

Contribution guidelines and development setup