@red-hat-developer-hub/cli

This repository hosts the source code for the rhdh-cli utility, a new command-line interface designed to streamline the development, packaging, and distribution of dynamic plugins for Red Hat Developer Hub (RHDH).

This new CLI aims to offer more flexibility and ease of use compared to the previous @janus-idp/cli.

Tip

Command Migration

If you were previously using @janus-idp/cli, here are the corresponding new commands in rhdh-cli:

Old Command	New Command
npx @janus-idp/cli package export-dynamic-plugin	npx @red-hat-developer-hub/cli plugin export
npx @janus-idp/cli package package-dynamic-plugins	npx @red-hat-developer-hub/cli plugin package

plugin package requirements

The plugin package command stages each dist-dynamic plugin with npm pack and tar (via a short bash script). The following must be available on your PATH:

• bash — runs the pack/extract script
• npm (7 or newer) — npm pack --pack-destination requires npm 7+
• tar — extracts the packed tarball into the staging directory

On Windows, use Git Bash or WSL so these tools are available.

When you build an OCI image with --tag (instead of exporting to a directory with --export-to), a container build tool must also be on PATH. podman is the default; you can select docker or buildah with --container-tool (for example --container-tool docker). Directory-only exports with --export-to do not need a container tool.

Checking Plugin Versions

Use plugin check-versions to compare a plugin's @backstage/* dependencies with the Backstage release used by an RHDH version:

rhdh-cli plugin check-versions --rhdh-version 2.0.0

Use --json for machine-readable output. To target a Backstage version directly, prefix it with backstage:, for example --rhdh-version backstage:1.54.0.

For air-gapped environments, provide a local release manifest with --manifest-file. --manifest-file avoids the Backstage manifest download; also set RHDH_OFFLINE=true to skip the RHDH GitHub metadata lookup.

When adding support for a new RHDH release, update RHDH_COMPATIBILITY_MATRIX in src/lib/rhdhVersion.ts with its Backstage version before releasing the corresponding CLI version. This matrix is maintained manually until its release metadata can be automated.

Upgrading Plugin Versions

Use plugin upgrade to update a plugin's @backstage/* dependencies to the versions from an RHDH release manifest:

rhdh-cli plugin upgrade --rhdh-version 2.0.0

The command also accepts the RHDH version as a positional argument, for example rhdh-cli plugin upgrade 2.0.0. Its plugin versions:bump alias provides the same behavior.

Use --dry-run to preview dependency changes without writing files and --skip-install to avoid updating the lockfile after applying changes. Use --json for machine-readable output.

For air-gapped environments, provide a local Backstage release manifest with --manifest-file and set RHDH_OFFLINE=true to skip the RHDH GitHub metadata lookup.

Creating a Plugin

Use plugin new to create a standalone, version-pinned dynamic plugin project:

rhdh-cli plugin new my-plugin --type frontend --rhdh-version 2.1.0

Supported types are frontend (a New Frontend System, or NFS, page), backend (a minimal new-backend-system plugin), and catalog-processor-module (a catalog processor module). Use --name <plugin-name> as an alternative to the positional name, and --output <directory> to select a destination. The generated project uses the target RHDH release's Backstage manifest for every @backstage/* dependency. For air-gapped environments, provide --manifest-file and set RHDH_OFFLINE=true. Export and package generated plugins with npx @red-hat-developer-hub/cli, or through RHDH Dynamic Plugin Factory, rather than adding the CLI as a project dependency.

Development

Contributing

Build and Run Locally

To build the project locally:

yarn install
yarn build

You can run the CLI locally by pointing to the bin/rhdh-cli file:

./bin/rhdh-cli

or when executing from the project root you can also use:

npx @red-hat-developer-hub/cli

Commands

The CLI provides two categories of commands:

Plugin Development Commands

• plugin export: Export a Backstage plugin as a dynamic plugin
• plugin package: Package dynamic plugins for distribution
• plugin check-versions: Verify plugin compatibility with RHDH versions

Intent-Based RHDH Interaction Commands

High-level commands for interacting with RHDH instances:

• auth: Log in to, select, inspect, and manage authenticated RHDH instances
• actions: List and execute actions, and manage action-discovery sources
• catalog: List, get, validate, register, and unregister catalog entities
• api: List API entities and retrieve their OpenAPI/AsyncAPI/GraphQL specifications
• search: Search catalog, TechDocs, and template content
• docs: Search TechDocs and, on RHDH instances with optional plugins, list entities, retrieve pages, and view coverage
• template: List, execute, and dry-run software templates

Quick Examples:

# Authenticate with your RHDH instance
rhdh-cli auth login --backend-url https://rhdh.example.com

# List production components
rhdh-cli catalog list --kind Component --filter spec.lifecycle=production

# Search documentation
rhdh-cli search "deployment guide" --types '["techdocs"]'

# Get API specification
rhdh-cli api get-spec --name my-api

# Execute a template
rhdh-cli template execute \
  --template-ref template:default/nodejs-service \
  --value name=my-app \
  --value owner=team-platform

All commands support --help for detailed usage and --output json for machine-readable output.

📚 For complete documentation, setup guides, and examples, see:

• Intent-Based CLI Documentation - Complete guide for RHDH interaction commands

Optional TechDocs Features

TechDocs content retrieval (docs list, docs get, docs coverage, docs build):

• Requires TechDocs MCP extras plugin (techdocs-mcp-extras)
• See the CLI documentation for setup instructions

TechDocs search (docs search):

• Requires TechDocs search backend module (search-backend-module-techdocs)
• Standard Backstage plugin for indexing TechDocs content

All other commands work without these optional plugins.

Bumping Backstage Dependencies

To update the @backstage/* dependencies to a new Backstage release:

1. Update the --release version in the backstage:bump script in package.json to the target Backstage release version.
2. Check the resolutions section in package.json and update any pinned versions if needed.
3. Run the bump:

yarn backstage:bump

This will update all @backstage/* packages, pin them with ~ (tilde) ranges, keep @backstage/cli* packages at exact versions, and run yarn install && yarn dedupe.

After bumping, verify the build and tests still pass:

yarn build
yarn tsc
yarn test

Versioning Strategy

The versioning for rhdh-cli is designed to be straightforward and align directly with the main Red Hat Developer Hub (RHDH) product, ensuring a clear compatibility path for developers.

Our versioning scheme follows the pattern of $MAJOR.$MINOR.$PATCH (e.g., 1.8.0).

• Major and Minor Version ($MAJOR.$MINOR): This part of the version is synchronized with the corresponding RHDH release. For example, if you are working with RHDH 1.8.z, you should use a version of rhdh-cli from the 1.8.z series. This direct alignment removes ambiguity and the need to maintain a separate compatibility matrix.

• Patch Version ($PATCH): The patch version is incremented for new releases of the CLI that contain bug fixes or minor, non-breaking feature enhancements specific to the CLI. The patch version of rhdh-cli is not lock-stepped with RHDH's patch releases. For instance, rhdh-cli versions 1.8.0 and 1.8.1 are both intended for use with any RHDH 1.8.z installation. We always recommend using the latest available patch release for your RHDH version.

Release Process

Releases follow a straightforward manual workflow:

1. Update CHANGELOG.md: Add a new version heading (e.g., ## 2.0.5 - YYYY-MM-DD) following Keep a Changelog format, categorizing changes under Added, Changed, Fixed, etc., with links to relevant Jira issues and pull requests.
2. Bump version in package.json: Update the "version" field to the target version matching the Versioning Strategy.
3. Submit PR: Open a pull request titled chore: bump version to X.Y.Z and merge it after review and CI checks pass.
4. Publish: Trigger the Publish Package to NPM GitHub Action workflow for the target branch.

Publishing to NPM

Publishing is done using Publish Package to NPM workflow.

Make sure not to release MINOR or MAJOR version that are not aligned with the corresponding RHDH release.

This workflow is not currently triggered automatically. It needs to be run manually from the Actions tab in the GitHub repository. Always run the workflow from the main branch (the "Use workflow from" dropdown) and select the target release branch via the branch input parameter. This ensures the latest workflow definition is used.

NPM dist-tags

The workflow automatically assigns npm dist-tags based on the selected branch:

Branch	Dist-tag	Example
main	next	npm install @red-hat-developer-hub/cli@next
Latest GA release branch (auto-detected)	latest + branch name	npm install @red-hat-developer-hub/cli@latest or @release-1.10
Older release branches	Branch name (e.g., release-1.9)	npm install @red-hat-developer-hub/cli@release-1.9

The latest GA branch is auto-detected as the release-* branch with the highest semver version. Plugin builders targeting a specific RHDH version should use a semver range (e.g., ~1.10.0) or the corresponding branch tag rather than latest.

Reporting Issues

If you encounter any bugs or have feature requests, please report them through our Jira Project Red Hat Developer Hub (RHIDP)