Red Hat Developer Hub 1.10

Querying and managing Red Hat Developer Hub with the rhdh-cli command-line interface

Query and manage RHDH catalog entities, APIs, TechDocs, and software templates from your terminal, and let AI agents run those operations on your instance

Red Hat Customer Content Services

Abstract

The rhdh-cli command-line interface (CLI) provides intent-based commands for querying and managing Red Hat Developer Hub (RHDH) catalog entities, APIs, TechDocs, and software templates from your terminal. You can script these operations or let AI agents run them on your instance.

Preface
1. rhdh-cli for automation and AI agents
2. Install rhdh-cli to run operations from your terminal
3. Configure Red Hat Developer Hub to authenticate rhdh-cli
4. Authenticate and register action sources to run commands on an instance
5. rhdh-cli command groups for RHDH task automation

Preface

Chapter 1. rhdh-cli for automation and AI agents

rhdh-cli is a command-line interface (CLI) that provides terminal access to Red Hat Developer Hub (RHDH) catalog, scaffolder, and TechDocs operations to automate repeatable tasks without using the web UI.

The intent-based catalog, api, search, docs, and template commands can return structured JSON output with the --output json flag, and commands set a nonzero exit code on failure. As a result, you can call rhdh-cli from scripts, continuous integration pipelines, and AI agents that run operations on your instance.

You can use rhdh-cli to complete the following tasks:

List, inspect, validate, and register catalog entities and APIs.
Search the catalog, software templates, and TechDocs from one command.
Run and dry-run software templates to scaffold new components.
Trigger and read TechDocs builds and coverage.
Discover and run the actions that your installed plugins expose.

You can query and manage RHDH through Backstage actions using command groups in intent-based workflows. Additional commands for tasks such as plugin development and packaging are documented separately.

The CLI authenticates against each instance separately, enabling you to target several RHDH instances from the same workstation and switch between them as needed.

Chapter 2. Install rhdh-cli to run operations from your terminal

To run Red Hat Developer Hub (RHDH) operations from your terminal, install rhdh-cli, the command-line interface (CLI) for RHDH, from the npm registry.

Prerequisites

You have installed Node.js and the npm package manager.
Your workstation can reach the public npm registry.

Procedure

Install rhdh-cli globally:
```
$ npm install -g @red-hat-developer-hub/cli
```
To run the CLI without a global installation, prefix each command with npx @red-hat-developer-hub/cli instead.

Verification

Confirm that the CLI is available:
```
$ rhdh-cli --help
```

Chapter 3. Configure Red Hat Developer Hub to authenticate rhdh-cli

To allow rhdh-cli to sign in to an instance, enable the authentication plugin and the OAuth2 flows that the command-line interface (CLI) uses to obtain and refresh tokens.

Prerequisites

You are running Red Hat Developer Hub (RHDH) 2.1 or later.
You have installed rhdh-cli 2.0.9 or later.
You have administrative access to the RHDH configuration.
You can install dynamic plugins on your instance.

Procedure

Install the backstage-plugin-auth front-end plugin as a dynamic plugin so that your instance can serve the OAuth2 consent page. Add the following entry to your dynamic-plugins.yaml file, which registers the /oauth2/* route that the consent flow requires:
Note
The plugin image tags in the following examples target Red Hat Developer Hub 2.1, which uses Backstage 1.54.6. For any new RHDH release, use plugin images built for that release’s Backstage version.
```
plugins:
  - package: 'oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/backstage-plugin-auth:bs_1.54.6__0.1.11'
    disabled: false
    pluginConfig:
      dynamicPlugins:
        frontend:
          backstage.plugin-auth:
            dynamicRoutes:
              - path: /oauth2/*
                importName: Router
```
For more information about installing dynamic plugins, see Installing and viewing plugins in Red Hat Developer Hub.
In your app-config file, enable the OAuth2 client ID metadata documents and refresh token flows that the CLI requires:
```
auth:
  clientIdMetadataDocuments:
    enabled: true
  experimentalRefreshToken:
    enabled: true
```
Note
The clientIdMetadataDocuments key applies to Backstage 1.53 and later, which Red Hat Developer Hub 2.1 uses. On earlier versions, use experimentalClientIdMetadataDocuments, which remains available as a deprecated alias in later releases.
Save the file and restart your instance to apply the configuration.

Verification

Sign in from the CLI as described in Authenticate and register action sources. A successful login confirms that RHDH accepts the CLI authentication flows.

Chapter 4. Authenticate and register action sources to run commands on an instance

To run commands against a Red Hat Developer Hub (RHDH) instance, sign in with rhdh-cli and register the plugin action sources for the command-line interface (CLI) to use.

The CLI stores credentials and registered action sources per instance. Repeat these steps for each target instance.

Prerequisites

You are running Red Hat Developer Hub (RHDH) 2.1 or later.
You have installed rhdh-cli 2.0.9 or later.
You have configured your instance to support the CLI authentication flows.
You have the back-end URL of your RHDH instance.

Procedure

Sign in to your instance:
```
$ rhdh-cli auth login --backend-url https://rhdh.example.com
```
Complete the OAuth2 consent flow in your browser when prompted.
Confirm the active instance:
```
$ rhdh-cli auth show
```
Register each plugin action source that you want to use. For example, to register the catalog, scaffolder, search, and authentication sources, run:
```
$ rhdh-cli actions sources add catalog
$ rhdh-cli actions sources add scaffolder
$ rhdh-cli actions sources add search
$ rhdh-cli actions sources add auth
```
Register additional sources, such as notifications, only after you install the corresponding plugins on your instance.

Verification

List the registered action sources:
```
$ rhdh-cli actions sources list
```

Chapter 5. rhdh-cli command groups for RHDH task automation

rhdh-cli groups the commands used in intent-based workflows by plugin area to list and act on Red Hat Developer Hub (RHDH) catalog entities, APIs, software templates, TechDocs, and plugin actions from one tool.

The following table lists the command groups used in intent-based workflows. rhdh-cli also provides other commands, such as plugin development and packaging commands, that are outside the scope of this reference.

Table 5.1. rhdh-cli command groups used in intent-based workflows

Command group	Description
`catalog`	List, get, validate, register, and unregister catalog entities.
`api`	List API entities and retrieve API specifications.
`search`	Search the catalog, software templates, and TechDocs.
`docs`	List, get, build, and report coverage for TechDocs content.
`template`	List software templates, run a dry-run, and run templates to scaffold components.
`auth`	Sign in and out, list authenticated instances, and select the active instance.
`actions`	List and run plugin actions and manage action sources.

Note

The docs list, docs get, and docs coverage commands require the techdocs-mcp-extras plugin. Install it as a dynamic plugin, and then register it as an action source with rhdh-cli actions sources add techdocs-mcp-extras:

plugins:
  - package: oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/red-hat-developer-hub-backstage-plugin-techdocs-mcp-extras:bs_1.54.6__0.2.6
    disabled: false

The docs search command additionally requires the TechDocs search backend plugin, search-backend-module-techdocs:

plugins:
  - package: 'oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/backstage-plugin-search-backend-module-techdocs:bs_1.54.6__0.4.17'
    disabled: false

The following flags are available on every command:

--help: Displays command usage and options.
--instance <name>: Targets a specific authenticated instance.

The intent-based catalog, api, search, docs, and template commands also support the following flag:

--output json: Returns structured JSON for automation.

The following flags are available on list and query commands, such as catalog list:

--limit <n>: Restricts the number of results.
--filter <key=value>: Applies a query predicate. Repeat the flag to combine predicates.
--fields <list>: Selects the fields to include in the output.

Commands return an exit code of 0 on success and a nonzero exit code on failure.

For the complete list of commands and options, run rhdh-cli --help, or append --help to any command. For more information, see the intent-based CLI reference in the rhdh-cli repository.

Legal Notice

The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at http://creativecommons.org/licenses/by-sa/3.0/. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version.

Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.

Red Hat, Red Hat Enterprise Linux, the Shadowman logo, the Red Hat logo, JBoss, OpenShift, Fedora, the Infinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.

Linux® is the registered trademark of Linus Torvalds in the United States and other countries.

Java® is a registered trademark of Oracle and/or its affiliates.

XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.

MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.

Node.js® is an official trademark of Joyent. Red Hat is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.

The OpenStack® Word Mark and OpenStack logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.

All other trademarks are the property of their respective owners.