@herodevs/cli

The HeroDevs CLI

Terms and Data Security

Prerequisites

Install node v20 or higher: Download Node
The HeroDevs CLI expects that you have all required technology installed for the project that you are running the CLI against
- For example, if you are running the CLI against a Gradle project, the CLI expects you to have Java installed.

Installation methods

Node Package Execute (NPX)

With Node installed, you can run the CLI directly from the npm registry without installing it globally or locally on your system

npx @herodevs/cli

Global NPM Installation

npm install -g @herodevs/cli

Binary Installation

HeroDevs CLI is available as a binary installation, without requiring npm. To do that, you may either download and run the script manually, or use the following cURL or Wget command:

curl -o- https://raw.githubusercontent.com/herodevs/cli/v2.0.8/scripts/install.sh | bash

wget -qO- https://raw.githubusercontent.com/herodevs/cli/v2.0.8/scripts/install.sh | bash

Scanning Behavior

The CLI is designed to be non-invasive:

It does not install dependencies or modify package manager files (package-lock.json, yarn.lock, etc.)
It analyzes the project in its current state

Installing Dependencies Before Use

Some projects and ecosystems require projects to have dependencies installed already, to achieve an accurate scan result. It is highly recommended that you install all dependencies of your project to your working directory, before running a scan on your project, to ensure scan accuracy.

Java Users

Maven and Gradle projects should run an install and build before scanning

Usage

$ npm install -g @herodevs/cli
$ hd COMMANDrunning command...
$ hd (--version|-v)@herodevs/cli/2.0.8 darwin-arm64 node-v24.13.1
$ hd --help [COMMAND]USAGE $ hd COMMAND...

`hd auth login`

OAuth CLI login

USAGE
$ hd auth login
DESCRIPTION
OAuth CLI login

See code: src/commands/auth/login.ts

`hd auth logout`

Logs out of HeroDevs OAuth and clears stored tokens

USAGE
$ hd auth logout
DESCRIPTION
Logs out of HeroDevs OAuth and clears stored tokens

See code: src/commands/auth/logout.ts

`hd auth provision-ci-token`

Provision a CI/CD long-lived refresh token for headless auth

USAGE
$ hd auth provision-ci-token
DESCRIPTION
Provision a CI/CD long-lived refresh token for headless auth

See code: src/commands/auth/provision-ci-token.ts

`hd help [COMMAND]`

Display help for hd.

USAGE
$ hd help [COMMAND...] [-n]
ARGUMENTS
[COMMAND...] Command to show help for.
FLAGS
-n, --nested-commands Include all nested commands in the output.
DESCRIPTION
Display help for hd.

See code: @oclif/plugin-help

`hd report committers`

Generate report of committers to a git repository

USAGE
$ hd report committers [--json] [-x <value>...] [-d <value>] [--monthly] [-m <value> | -s <value> | -e <value> | | ]
[-c] [-s]
FLAGS
-c, --csv Output in CSV format
-d, --directory=<value> Directory to search
-e, --afterDate=<value> [default: 2025-07-17] Start date (format: yyyy-MM-dd)
-m, --months=<value> [default: 12] The number of months of git history to review. Cannot be used along beforeDate
and afterDate
-s, --beforeDate=<value> [default: 2026-07-17] End date (format: yyyy-MM-dd)
-s, --save Save the committers report as herodevs.committers.<output>
-x, --exclude=<value>... Path Exclusions (eg -x="./src/bin" -x="./dist")
--json Output to JSON format
--monthly Break down by calendar month.
DESCRIPTION
Generate report of committers to a git repository
EXAMPLES
$ hd report committers
$ hd report committers --csv -s
$ hd report committers --json
$ hd report committers --csv

See code: src/commands/report/committers.ts

`hd scan eol`

Scan a given SBOM for EOL data

USAGE
$ hd scan eol [--json] [-f <value> | -d <value>] [-s] [-o <value>] [--saveSbom] [--sbomOutput <value>]
[--saveTrimmedSbom] [--hideReportUrl] [--automated]
FLAGS
-d, --dir=<value> [default: <current directory>] The directory to scan in order to create a cyclonedx SBOM
-f, --file=<value> The file path of an existing SBOM to scan for EOL (supports CycloneDX and SPDX 2.3 formats)
-o, --output=<value> Save the generated report to a custom path (defaults to herodevs.report.json when not
provided)
-s, --save Save the generated report as herodevs.report.json in the scanned directory
--automated Mark scan as automated (for CI/CD pipelines)
--hideReportUrl Hide the generated web report URL for this scan
--saveSbom Save the generated SBOM as herodevs.sbom.json in the scanned directory
--saveTrimmedSbom Save the trimmed SBOM as herodevs.sbom-trimmed.json in the scanned directory
--sbomOutput=<value> Save the generated SBOM to a custom path (defaults to herodevs.sbom.json when not provided)
GLOBAL FLAGS
--json Format output as json.
DESCRIPTION
Scan a given SBOM for EOL data
EXAMPLES
Default behavior (no command or flags specified)
$ hd
Equivalent to
$ hd scan eol --dir .
Skip SBOM generation and specify an existing file
$ hd scan eol --file /path/to/sbom.json
Save the report or SBOM to a file
$ hd scan eol --save --saveSbom
Output the report in JSON format (for APIs, CI, etc.)
$ hd scan eol --json

See code: src/commands/scan/eol.ts

`hd tracker init`

Initialize the tracker configuration

USAGE
$ hd tracker init [--force -o] [-d <value>] [-f <value>] [-i <value>...]
FLAGS
-d, --outputDir=<value> [default: hd-tracker] Output directory for the tracker configuration file
-f, --configFile=<value> [default: config.json] Filename for the tracker configuration file
-i, --ignorePatterns=<value>... [default: node_modules] Ignore patterns to use for the tracker configuration file
-o, --overwrite Overwrites the tracker configuration file if it exists
--force Force tracker configuration file creation. Use with --overwrite flag
DESCRIPTION
Initialize the tracker configuration
EXAMPLES
$ hd tracker init
$ hd tracker init -d trackerDir
$ hd tracker init -d trackerDir -f configFileName
$ hd tracker init -i node_modules
$ hd tracker init -i node_modules -i custom_modules
$ hd tracker init -o

See code: src/commands/tracker/init.ts

`hd tracker run`

Run the tracker

USAGE
$ hd tracker run [-d <value>] [-f <value>]
FLAGS
-d, --configDir=<value> [default: hd-tracker] Directory where the tracker configuration file resides
-f, --configFile=<value> [default: config.json] Filename for the tracker configuration file
DESCRIPTION
Run the tracker
EXAMPLES
$ hd tracker run
$ hd tracker run -d tracker-configuration
$ hd tracker run -d tracker -f settings.json

See code: src/commands/tracker/run.ts

`hd update [CHANNEL]`

update the hd CLI

USAGE
$ hd update [CHANNEL] [--force | | [-a | -v <value> | -i]] [-b ]
FLAGS
-a, --available See available versions.
-b, --verbose Show more details about the available versions.
-i, --interactive Interactively select version to install. This is ignored if a channel is provided.
-v, --version=<value> Install a specific version.
--force Force a re-download of the requested version.
DESCRIPTION
update the hd CLI
EXAMPLES
Update to the stable channel:
$ hd update stable
Update to a specific version:
$ hd update --version 1.0.0
Interactively select version:
$ hd update --interactive
See available versions:
$ hd update --available

See code: @oclif/plugin-update

CI/CD Usage

You can use @herodevs/cli in your CI/CD pipelines to automate EOL scanning.

CI/CD authentication

For headless use in CI/CD (e.g. GitHub Actions, GitLab CI), the CLI supports long-lived organization-scoped refresh tokens. You do not need to run an interactive login in the pipeline.

One-time setup (interactive):

hd auth login
hd auth provision-ci-token

Copy the token output, add as an environment variable: HD_CI_CREDENTIAL

CI pipeline (headless): Run hd scan eol directly with HD_CI_CREDENTIAL set. The CLI exchanges the token for an access token automatically. An explicit auth login command is not required when using the CI token.

export HD_CI_CREDENTIAL="<token>"
hd scan eol

Secret / Env Var	Purpose
`HD_CI_CREDENTIAL`	Refresh token from provision; exchanged for access token

GitHub Actions (authenticated scan)

Add secret HD_CI_CREDENTIAL in your repository or organization, then:

- uses: actions/checkout@v5
- uses: actions/setup-node@v6with:
node-version: '24'
- name: Run EOL Scanenv:
HD_CI_CREDENTIAL: ${{ secrets.HD_CI_CREDENTIAL }}run: npx @herodevs/cli scan eol -s

GitLab CI (authenticated scan)

Add CI/CD variable HD_CI_CREDENTIAL (masked) in your project:

eol-scan:
image: node:24variables:
HD_CI_CREDENTIAL: $HD_CI_CREDENTIALscript:
- npx @herodevs/cli scan eol -sartifacts:
paths:
- herodevs.report.json

Using the Docker Image

We provide a Docker image that's pre-configured to run EOL scans. Based on cdxgen, it contains build tools for most project types and will provide best results when generating an SBOM. Use these templates to generate a report and save it to your CI job artifact for analysis and processing after your scan runs.

Note: There is a potential to run into permission issues writing out the report to your CI runner. Please ensure that your CI runner is setup to have proper read/write permissions for wherever your output files are being written to.

GitHub Actions

## .github/workflows/herodevs-eol-scan.ymlname: HeroDevs EOL Scanon:
push:
branches: [ main ]pull_request:
branches: [ main ]jobs:
scan:
runs-on: ubuntu-latestenvironment: demosteps:
- name: Checkout repositoryuses: actions/checkout@v5
- name: Run EOL Scanrun: | docker run --name eol-scanner \ -v $GITHUB_WORKSPACE:/app \ -w /app \ ghcr.io/herodevs/eol-scan --save --output /tmp/herodevs.report.json docker cp eol-scanner:/tmp/herodevs.report.json ${{ runner.temp }}/herodevs.report.json docker rm eol-scanner - name: Upload artifactuses: actions/upload-artifact@v5with:
name: my-eol-reportpath: ${{ runner.temp }}/herodevs.report.json

GitLab CI/CD

eol-scan: image: name: "ghcr.io/herodevs/eol-scan"# Entrypoint or base command must be disabled due # to GitLab's execution mechanism and run manuallyentrypoint: [""] script: "npx @herodevs/cli scan eol -s"artifacts:
paths:
- herodevs.report.json

Using `npx` in CI

You can use npx to run the CLI in your CI pipeline, just like you would run it locally.

Note

The development environment is expected to be ready to run the app. For best results, prefer using the prebuilt image, but otherwise, prepare all requirements before the scan step.

GitHub Actions

## .github/workflows/herodevs-eol-scan.ymlname: HeroDevs EOL Scanon:
push:
branches: [ main ]pull_request:
branches: [ main ]jobs:
scan:
runs-on: ubuntu-lateststeps:
- uses: actions/checkout@v5
- uses: actions/setup-node@v6with:
node-version: '24'
- run: echo # Prepare environment, install tooling, perform setup, etc.
- name: Run EOL Scanrun: npx @herodevs/cli scan eol
- name: Upload artifactuses: actions/upload-artifact@v5with:
name: my-eol-reportpath: herodevs.report.json

GitLab CI/CD

image: alpineeol-scan:
script:
- echo # Prepare environment, install tooling, perform setup, etc.
- npx @herodevs/cli scan eol -sartifacts:
paths:
- herodevs.report.json

Local Docker image scans

The same pre-configured image can be pulled locally to scan in an optimized environment. Mount your code to /app or a specified working directory to perform the scan:

docker run -v "$PWD":/app ghcr.io/herodevs/eol-scan

Name		Name	Last commit message	Last commit date
.github		.github
.vscode		.vscode
bin		bin
ci		ci
e2e		e2e
scripts		scripts
src		src
test		test
.cursorrules		.cursorrules
.envrc.example		.envrc.example
.gitignore		.gitignore
.nvmrc		.nvmrc
.release-please-manifest.json		.release-please-manifest.json
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
biome.json		biome.json
commitlint.config.js		commitlint.config.js
package-lock.json		package-lock.json
package.json		package.json
release-please-config.json		release-please-config.json
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

Uh oh!

Latest commit

History

Folders and files

Repository files navigation

@herodevs/cli

Table of Contents

Terms and Data Security

Prerequisites

Installation methods

Node Package Execute (NPX)

Global NPM Installation

Binary Installation

Scanning Behavior

Installing Dependencies Before Use

Java Users

Usage

Commands

hd auth login

hd auth logout

hd auth provision-ci-token

hd help [COMMAND]

hd report committers

hd scan eol

hd tracker init

hd tracker run

hd update [CHANNEL]

CI/CD Usage

CI/CD authentication

GitHub Actions (authenticated scan)

GitLab CI (authenticated scan)

Using the Docker Image

GitHub Actions

GitLab CI/CD

Using npx in CI

GitHub Actions

GitLab CI/CD

Local Docker image scans

About

Resources

Contributing

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages

`hd auth login`

`hd auth logout`

`hd auth provision-ci-token`

`hd help [COMMAND]`

`hd report committers`

`hd scan eol`

`hd tracker init`

`hd tracker run`

`hd update [CHANNEL]`

Using `npx` in CI