From 051903329b72f39edfa23a74903231b5d9dfb1a1 Mon Sep 17 00:00:00 2001
From: Tomas Kral <tkral@redhat.com>
Date: Fri, 29 May 2026 11:36:14 +0200
Subject: [PATCH 1/2] docs: add backstage-cli usage guide for RHDH

Document how to use @backstage/cli auth and actions commands with RHDH,
including auth plugin setup, OAuth2 endpoint configuration, standalone
usage workaround for npm peer dependency conflicts, and troubleshooting.

Assisted-by: Claude Code
---
 docs/backstage-cli.md | 85 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 85 insertions(+)
 create mode 100644 docs/backstage-cli.md

diff --git a/docs/backstage-cli.md b/docs/backstage-cli.md
new file mode 100644
index 0000000000..5f0d566251
--- /dev/null
+++ b/docs/backstage-cli.md
@@ -0,0 +1,85 @@
+# Using backstage-cli with RHDH
+
+The `@backstage/cli auth` command provides CLI-based authentication to a Backstage instance using OAuth2 with PKCE. This enables programmatic access to catalog entities, scaffolder actions, and other Backstage APIs without a browser session.
+
+
+## Prerequisites
+
+### Enable the auth plugin
+
+The `backstage-cli auth` flow requires the `@backstage/plugin-auth` frontend plugin to serve the OAuth2 consent page at `/oauth2/authorize/:sessionId`. RHDH does not include this plugin by default.
+
+Install it as a dynamic plugin from the [rhdh-plugin-export-overlays](https://github.com/redhat-developer/rhdh-plugin-export-overlays) registry:
+
+```yaml
+# dynamic-plugins.yaml
+plugins:
+  - package: "oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/backstage-plugin-auth:bs_1.49.4__0.1.6"
+    disabled: false
+    pluginConfig:
+      dynamicPlugins:
+        frontend:
+          backstage.plugin-auth:
+            dynamicRoutes:
+              - path: /oauth2/*
+                importName: Router
+```
+
+Replace `<tag>` with the appropriate version tag from the registry.
+
+### Enable the OAuth2 server endpoints
+
+Add the following to your `app-config.local.yaml`:
+
+```yaml
+auth:
+  experimentalClientIdMetadataDocuments:
+    enabled: true
+  experimentalRefreshToken:
+    enabled: true
+```
+
+This enables the backend OAuth2 endpoints.
+
+
+## Running backstage-cli
+
+The CLI is published as `@backstage/cli` on npm. But it can't be run outside of a Backstage or RHDH project directory. See [standalone usage](#standalone-usage) for more information.  Run it from within a Backstage or RHDH project directory:
+
+```bash
+npx @backstage/cli auth login --backend-url <RHDH_URL>
+npx @backstage/cli auth list
+npx @backstage/cli actions list
+```
+
+### Standalone usage
+
+`@backstage/cli` bundles build tooling alongside the `auth` and `actions` subcommands. The package declares optional peer dependencies on `jsdom@^27.1.0` and `jest-environment-jsdom`, but `jest-environment-jsdom` pulls in `jsdom@29.x` as a regular dependency. npm 7+ auto-resolves peer dependencies and fails with `ERESOLVE` when it can't satisfy both `^27.1.0` and `29.x` at the same level — even though these dependencies are optional and never used by the `auth` or `actions` commands.
+
+Inside a Backstage project this works because the project lockfile already has compatible versions resolved. To run standalone, set `NPM_CONFIG_LEGACY_PEER_DEPS=true` to tell npm to skip auto-installing peer dependencies (the pre-npm 7 behavior):
+
+```bash
+NPM_CONFIG_LEGACY_PEER_DEPS=true npx -y @backstage/cli auth login --backend-url <RHDH_URL>
+```
+
+Or define a shell alias for convenience:
+
+```bash
+alias backstage-cli='NPM_CONFIG_LEGACY_PEER_DEPS=true npx -y @backstage/cli'
+```
+
+Then use it from any directory without a Backstage checkout:
+
+```bash
+backstage-cli auth login --backend-url http://localhost:7007
+backstage-cli auth list
+backstage-cli actions sources add catalog
+backstage-cli actions list
+```
+
+## Troubleshooting
+
+### 404 on /oauth2/authorize
+
+The `@backstage/plugin-auth` frontend plugin is not loaded. Verify the dynamic plugin configuration and check pod logs for plugin loading errors.
+

From b8506ea25d4d85aef9bea9b9fb7e420b65372f50 Mon Sep 17 00:00:00 2001
From: Tomas Kral <tkral@redhat.com>
Date: Fri, 29 May 2026 11:51:00 +0200
Subject: [PATCH 2/2] docs: add RHDH 1.10 version requirement to backstage-cli
 guide

Assisted-by: Claude Code
---
 docs/backstage-cli.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/docs/backstage-cli.md b/docs/backstage-cli.md
index 5f0d566251..2ffabfb7b4 100644
--- a/docs/backstage-cli.md
+++ b/docs/backstage-cli.md
@@ -2,6 +2,7 @@
 
 The `@backstage/cli auth` command provides CLI-based authentication to a Backstage instance using OAuth2 with PKCE. This enables programmatic access to catalog entities, scaffolder actions, and other Backstage APIs without a browser session.
 
+**Requires RHDH 1.10 or later.**
 
 ## Prerequisites