Boss is an open source dependency manager inspired by npm for projects developed in Delphi and Lazarus.

We have a Getting Started article to help you get started with Boss.

• Download setup
• Just type boss in the terminal
• (Optional) Install a Boss Delphi IDE complement

Or you can use the following the steps below:

• Download the latest version of the Boss
• Extract the files to a folder
• Add the folder to the system path
• Run the command boss in the terminal

This section documents all commands supported by the Boss CLI, grouped in the exact order they appear in boss --help.

These are the classic dependency management commands inherited from the original Boss engine.

Manage configuration settings for Boss (e.g., Delphi paths, Git client settings, etc.):

# Set native Git client (recommended on Windows)
boss config git mode native

# Enable shallow cloning for faster dependency checkout
boss config git shallow true

List all project dependencies in a tree format. Add -v to show version information:

boss dependencies
boss dependencies -v
boss dependencies <package>

Aliases: dep, ls, list, ll, la, dependency

Initialize a new, minimal project configuration in the current directory and create a boss.json file:

boss init
boss init --quiet  # Skip interactive prompts

Install one or more dependencies defined in the boss.json file or add a new dependency:

# Install dependencies from boss.json
boss install

# Add and install a new dependency
boss install github.com/HashLoad/horse

Aliases: i, add

Remove saved credentials for a private repository or registry:

boss logout github.com/username

Remove a dependency from the current project:

boss uninstall <dependency>

Aliases: remove, rm, r, un, unlink

Update all installed dependencies to their latest compatible versions:

boss update

Aliases: up

Upgrade the Boss CLI client to the latest version:

boss upgrade
boss upgrade --dev  # Upgrade to the latest pre-release

Show the Boss CLI version:

boss version
boss --version

Aliases: v

These commands add modern project creation, compiling, and script running capabilities to Boss.

Generate a fully structured Delphi or Lazarus project template (skeleton) in the current directory:

boss new my_project
boss new my_project --ide lazarus
boss new my_package --type pkg --ide lazarus

Perform Delphi package manifest operations.

• pkg spec: Scaffolds a starter pubpascal.json manifest file for the package:

  boss pkg spec --id my-package --pkgversion 1.0.0

Execute a custom shell script defined in the scripts section of your boss.json file:

{
  "scripts": {
    "build": "msbuild MyProject.dproj /p:Config=Release",
    "clean": "del /s *.dcu"
  }
}

boss run build
boss run clean

These commands integrate your local development workflow with the PubPascal Portal.

Authenticate your local environment with the PubPascal portal using a Personal Access Token (PAT):

# Authenticate using a personal access token
boss login --token <pat>

Contribute to a third-party package by automating repository forking and Pull Request creation.

• Fork & Setup: Automatically forks the upstream package and configures your local git remotes (origin for your fork and upstream for the original):

  boss contribute github.com/HashLoad/horse

• Submit Pull Request: Once your commits are ready, push changes and submit a Pull Request to the original repository with one command:

  boss contribute github.com/HashLoad/horse --pr --title "Fix memory leak" --body "..."

Manage multi-repository PubPascal workspaces locally.

• workspace clone: Clones a workspace and all its member repositories, checking out the reference each one is pinned to:

  boss workspace clone <workspace-id>
  boss workspace clone <workspace-id> --codename my-branch

• workspace status: Show Git status (ahead/behind/dirty) for all repositories in the workspace:

  boss workspace status

• workspace update: Fast-forward each repository on its current branch:

  boss workspace update

• workspace push: Push committed changes for each repository that has an upstream branch:

  boss workspace push

These native commands help you achieve 100% Cyber Resilience Act (CRA) compliance.

Check your project's CRA compliance status or initialize required files automatically.

• cra (Diagnose): Scan the local project for required CRA signals (Security Policy, SBOM). It exits with status 1 when a signal is missing, so it can be used as a CI gate:

  boss cra

• cra init (Wizard): Start the interactive wizard to generate the SECURITY.md policy and sbom.cdx.json SBOM:

  boss cra init
  boss cra init --email security@yourcompany.com  # Silent/CI mode

Generate a standard CycloneDX or SPDX Software Bill of Materials (SBOM) for your Delphi project:

# Generate CycloneDX SBOM (outputs to ./sbom/<ProjectName>.cdx.json)
boss sbom

# Specify custom project file and output path
boss sbom --project ./src/MyProj.dproj --output ./custom-sbom-folder

# Generate in SPDX format
boss sbom --format spdx

Manage the Boss local cache to clear downloaded modules and free up disk space:

boss config cache rm

Aliases: purge, clean

Generate the autocompletion script for the specified shell (bash, zsh, fish, or powershell):

boss completion powershell | Out-String | Invoke-Expression

• -g, --global: Use global environment for installation (packages are available system-wide):

  boss install -g <dependency>

• -d, --debug: Enable debug mode to see detailed output:

  boss install -d

• -h, --help: Show help for any command:

  boss --help
  boss install --help

• -v, --version: Show CLI client version:

  boss --version

Configure which Delphi version Boss should use for compiling packages:

# List all detected Delphi installations
boss config delphi list

# Select a Delphi version to use globally
boss config delphi use <index>
boss config delphi use 37.0
boss config delphi use 37.0-Win64

boss install horse
boss install horse:1.0.0
boss install -g delphi-docker
boss install -g boss-ide

You can specify which update types your package can accept from dependencies in your package's boss.json file.

For example, to specify acceptable version ranges up to 1.0.4, use the following syntax:

• Patch releases: 1.0 or 1.0.x or ~1.0.4
• Minor releases: 1 or 1.x or ^1.0.4
• Major releases: * or x

The boss.json file is the manifest for your Delphi/Lazarus project. It contains metadata, dependencies, build configuration, and custom scripts.

Here's a comprehensive example showing all available fields:

{
  "name": "my-project",
  "description": "A sample Delphi project using Boss",
  "version": "1.0.0",
  "homepage": "https://github.com/myuser/my-project",
  "mainsrc": "src/",
  "browsingpath": "src/;libs/",
  "projects": [
    "MyProject.dproj",
    "MyPackage.dproj"
  ],
  "dependencies": {
    "github.com/HashLoad/horse": "^3.0.0",
    "github.com/HashLoad/jhonson": "~2.1.0",
    "dataset-serialize": "*"
  },
  "scripts": {
    "build": "msbuild MyProject.dproj /p:Config=Release",
    "test": "MyProject.exe --test",
    "clean": "del /s *.dcu"
  },
  "engines": {
    "compiler": ">=35.0",
    "platforms": ["Win32", "Win64"]
  },
  "toolchain": {
    "compiler": "37.0",
    "platform": "Win64",
    "path": "C:\\Program Files\\Embarcadero\\Studio\\37.0",
    "strict": false
  }
}

• name (required): Package name. Must be unique if publishing.

  "name": "my-awesome-library"

• description (optional): A brief description of your project.

  "description": "REST API framework for Delphi"

• version (required): Package version following semantic versioning.

  "version": "1.2.3"

• homepage (optional): Project website or repository URL.

  "homepage": "https://github.com/myuser/my-project"

• mainsrc (optional): Main source directory path.

  "mainsrc": "src/"

• browsingpath (optional): Additional paths for IDE browsing (semicolon-separated).

  "browsingpath": "src/;src/controllers/;src/models/"

• projects (optional): List of Delphi project files (.dproj) to compile.

  "projects": [
    "MyProject.dproj",
    "MyLibrary.dproj"
  ]

  Note: If not specified, Boss won't compile the package but will still manage dependencies.

• dependencies (optional): Map of package dependencies with version constraints.

  "dependencies": {
    "github.com/HashLoad/horse": "^3.0.0",
    "dataset-serialize": "~2.1.0",
    "jhonson": "*"
  }

  Supported version formats:

  • Exact version: "1.0.0"
  • Caret (minor updates): "^1.0.0" (allows 1.x.x, but not 2.x.x)
  • Tilde (patch updates): "~1.0.0" (allows 1.0.x, but not 1.1.x)
  • Wildcard (any): "*" or "x"
  • Range: ">=1.0.0 <2.0.0"

• scripts (optional): Custom commands you can run with boss run <script-name>.

  "scripts": {
    "build": "msbuild MyProject.dproj /p:Config=Release",
    "test": "dunitx-console.exe MyProject.exe",
    "clean": "del /s *.dcu *.exe",
    "deploy": "xcopy /s /y bin\\*.exe deploy\\"
  }

  Execute with:

  boss run build
  boss run test

• engines (optional): Specify minimum compiler/platform requirements.

  "engines": {
    "compiler": ">=35.0",
    "platforms": ["Win32", "Win64", "Linux64"]
  }

  • compiler: Minimum compiler version
  • platforms: Supported target platforms

• toolchain (optional): Specify the exact toolchain to use for this project.

  "toolchain": {
    "compiler": "37.0",
    "platform": "Win64",
    "path": "C:\\Program Files\\Embarcadero\\Studio\\37.0",
    "strict": true
  }

  • compiler: Required compiler version
  • platform: Target platform ("Win32", "Win64", "Linux64", etc.)
  • path: Explicit path to the compiler (optional)
  • strict: If true, fails if the exact version is not found (default: false)

A basic, classic boss.json showing that Boss remains fully backwards-compatible and works out of the box with just dependency definitions:

{
  "name": "my-project",
  "version": "1.0.0",
  "dependencies": {
    "github.com/HashLoad/horse": "^3.0.0"
  }
}

Use boss init to create a new boss.json interactively:

boss init

Or use quiet mode for defaults:

boss init -q

{
  "name": "my-delphi-library",
  "description": "Utilities for Delphi applications",
  "version": "2.1.0",
  "homepage": "https://github.com/myuser/my-library",
  "mainsrc": "src/",
  "projects": [
    "MyLibrary.dproj"
  ],
  "dependencies": {
    "github.com/HashLoad/horse": "^3.0.0"
  }
}

{
  "name": "my-app",
  "description": "My awesome Delphi application",
  "version": "1.0.0",
  "projects": [
    "MyApp.dproj"
  ],
  "dependencies": {
    "github.com/HashLoad/horse": "^3.0.0"
  },
  "scripts": {
    "build": "msbuild MyApp.dproj /p:Config=Release",
    "run": "bin\\MyApp.exe",
    "test": "dunitx-console.exe bin\\MyAppTests.exe"
  },
  "toolchain": {
    "compiler": "37.0",
    "platform": "Win32"
  }
}