Roadie CLI

A command line tool to develop, build and deploy plugins compatible with Roadie.io.

Enables the possibility to rebuild and repackage standard Backstage plugins to be instantly deployable to Roadie instances.

Installation

Prerequisites: Node.js and NPM/Yarn installed.

You can install the command line tool globally as a node.js compatible package by using either NPM or Yarn.

• npm install -g @roadiehq/roadie-cli

OR

• yarn global add @roadiehq/roadie-cli

Commands

• plugin:build [options] Build a plugin

• plugin:dev [options] Run a plugin on dev mode

• roadie-entity:create [options] Create an entity in the roadie entity database

• roadie-entity:list [options] List entities in the roadie entity database

• roadie-entity:delete [options] Delete an entity from the roadie entity database

• roadie-entity-set:load [options] Load entities from a file into the roadie entity database

• contributing-users:scms [options] List configured SCM integrations in your Roadie instance

• contributing-users:repos [options] Download the list of repositories tracked in Roadie for a specific SCM

• contributing-users:count [options] Calculate contributing users by cloning repositories and counting unique committers

Developing a plugin with Roadie CLI

• Create a Backstage plugin either using the Backstage CLI or other means
• Install Roadie CLI
• Run Roadie CLI in development mode against the plugin you have created
  • roadie plugin:dev --location ~/Development/my-roadie-plugins/my-custom-plugin-folder/ --output ~/Development/temp --port 7046 Available options:

| Option | Name | Description | Example | |---------------|------------------|----------------------------------------------------------------------------------------------|:---------------------------------------------------------------------------------------| | --location -l | Location | (Required) The absolute path to the folder where your plugin resides | -l $PWD/my-plugin / -l /home/myname/Development/roadie-plugins/my-plugin | | --port -p | Port | (Required) HTTP Port to use for the local server to serve files from. | -p 8765 | | --output -o | Output directory | The absolute path to the folder where you want to generate the Roadie compatible plugin code | -o $PWD/my-plugin/dist / -o /home/myname/Development/roadie-plugins/my-plugin/dist |

Building a plugin for production

• Create a Backstage plugin either using the Backstage CLI or other means
• Install Roadie CLI
• Run Roadie CLI build command against the plugin folder you have created
  • roadie plugin:build --location ~/Development/my-roadie-plugins/my-custom-plugin-folder/ --host https://my-plugins.domain.com/myCustomPlugin

OR

• Run Roadie CLI build command against a published NPM package (Currently public packages in npmjs.org registry are supported):
  • roadie plugin:build --package @roadiehq/backstage-plugin-prometheus --host https://my-plugins.domain.com/prometheusPlugin

Available options:

| Option | Name | Description | Example | |-----------------|---------------------------|-------------------------------------------------------------------------------------------------------------------------|:---------------------------------------------------------------------------------------------------------------------------------| | --location -l | Location | (One of location or package is required) The absolute path to the folder where your plugin resides | -l $PWD/my-plugin / -l /home/myname/Development/roadie-plugins/my-plugin | | --package -p | Package | (One of location or package is required) NPM Package to use to build a Roadie Plugin | -p @roadiehq/backstage-plugin-prometheus | | --host -h | Host | (Required) Fully qualified URL to the location where these files will be hosted. The Production URL | -h https://my-plugins.domain.com/prometheusPlugin / -h https://calm-parfait-833e94.netlify.app | | --output -o | Output directory | The absolute path to the folder where you want to generate the Roadie compatible plugin code | -o $PWD/my-plugin/dist / -o /home/myname/Development/roadie-plugins/my-plugin/dist | | --workdir -w | Working directory | Used for cases where package option is used. A directory to use to download, unpackage and build the wanted NPM package | -w $PWD/my-plugin/temp / -w /home/myname/temp/downloads | | | --withUpload -u | Enable AWS S3 upload mode | A flag to upload generated files to S3. Bucket info is defined in env variable S3_BUCKET_NAME & S3_BUCKET_PREFIX | -u |

Deploying

The CLI creates bundled static assets containing JS and CSS files. These files can be deployed to any static asset hosting solutions as long as they support providing these assets via HTTPS protocol. Possible hosting solutions:

• Netlify
• GitHub Pages
• GitLab Pages
• Static Site hosted in AWS S3 frontend by CloudFront
• Microsoft Azure Static Website hosting
• CloudFlare Pages
• Self-hosted Nginx Webserver
• Self-hosted Apache Web Server

Deploying automatically to AWS S3

The CLI provides a build option flag --withUpload / -u to automatically upload the constructed static assets to an AWS S3 bucket. To configure the bucket and the path where the files should be uploaded configure the environment variables S3_BUCKET_NAME and S3_BUCKET_PREFIX to match the wanted values.

Security

There are multiple ways to secure static assets if needed. If you are hosting your code internally within your infrastructure the easiest approach to secure the files is to secure the Nginx/Apache webservers (or other solutions) behind a VPN connection. When hosting the files on a hosting provider it could be beneficial to use edge functions, if possible, to intercept and identify requests to static assets.

In most cases the plugin code itself is something that is not needed to be hosted in a secure environment. For more lightweight approach to security an obfuscation approach could be enough. This would happen if the produced assets would be hosted somewhere like https://mydomain.com/32f078b6-19a9-11ee-be56-0242ac120002 or similarly unguessable URL.

Regardless of the approach it is always best practice to not hardcode URLs, secrets or other sensitive information into the deployed plugin code, but to use Roadie proxies, broker and secrets instead to handle connections securely.

Calculating Contributing Users

The CLI provides commands to calculate the number of contributing users for your Roadie instance which is used for billing purposes. Contributing users are people who have committed code to repositories tracked in your Roadie catalog within the past 3 months.

Prerequisites

1. A Roadie API token (generate at Administration > Account in your Roadie instance)
2. An SCM token with read access to your repositories (Please create a fresh token to avoid impacting rate limits on your Roadie instance)
3. Git installed locally and available in PATH.

Quick Start

# Set your Roadie API token
export ROADIE_API_TOKEN="your-roadie-api-token"

# For GitHub.com
export GITHUB_TOKEN="your-github-token"
roadie contributing-users:count --scm github

# For GitHub Enterprise
export GHE_TOKEN="your-github-enterprise-token"
export GHE_HOST="github.mycompany.com"
roadie contributing-users:count --scm github-enterprise

Available Commands

List configured SCMs:

roadie contributing-users:scms

Download repository list:

# Download repos for a specific SCM
roadie contributing-users:repos --scm github --output repos.csv
roadie contributing-users:repos --scm github-enterprise --output ghe-repos.csv
roadie contributing-users:repos --scm gitlab --output gitlab-repos.csv
roadie contributing-users:repos --scm bitbucket
roadie contributing-users:repos --scm azure-devops

Calculate contributing users:

# Full calculation for GitHub.com
roadie contributing-users:count --scm github

# Full calculation for GitHub Enterprise
roadie contributing-users:count --scm github-enterprise

# With custom date range
roadie contributing-users:count --scm gitlab --host gitlab.mycompany.com --since 2024-01-01

# Using a pre-downloaded repos file
roadie contributing-users:count --scm github --repos-file repos.csv

# Specify custom output file (defaults to e.g. contributors-github-2025-12-22_14-30-45-123.txt)
roadie contributing-users:count --scm github --output my-contributors.txt

Environment Variables by SCM

| SCM | Required Variables | Optional Variables | |-----|-------------------|-------------------| | GitHub (github.com) | GITHUB_TOKEN | | | GitHub Enterprise | GHE_TOKEN, GHE_HOST | | | GitLab | GITLAB_TOKEN | GITLAB_HOST (default: gitlab.com) | | Bitbucket | BITBUCKET_AUTH_TOKEN | BITBUCKET_USER | | Azure DevOps | AZURE_TOKEN | AZURE_HOST (default: dev.azure.com) |

All commands also require ROADIE_API_TOKEN unless using --repos-file.

How It Works

1. The CLI fetches the list of repositories from your Roadie catalog via the API
2. For each repository, it performs a bare clone with blob filtering (minimal download)
3. It extracts unique committers from the git log for the specified time period
4. Results are deduplicated across all repositories and written to the output file

This approach ensures the calculation happens entirely within your infrastructure, so Roadie never needs access to your private repository contents.

Dev notes

To test the CLI locally during development:

yarn workspace @roadiehq/roadie-cli build
yarn workspace @roadiehq/roadie-cli exec roadie contributing-users:count --help

# Test against a local backend (use ROADIE_API_URL env var)