--- id: commands title: Commands description: Descriptions of all commands available in the CLI. --- This page lists all commands provided by the Backstage CLI, what they're for, and where to use them. ## help This command displays a help summary or detailed help screens for each command. Below is a cleaned up output of `yarn backstage-cli --help`: ```text new [options] Open up an interactive guide to creating new things in your app config:docs [options] Browse the configuration reference documentation config:print [options] Print the app configuration for the current package config:check [options] Validate that the given configuration loads and matches schema config:schema [options] Print configuration schema repo [command] Command that run across an entire Backstage project package [command] Lifecycle scripts for individual packages migrate [command] Migration utilities versions:bump [options] Bump Backstage packages to the latest versions translations [command] Translation message management clean Delete cache directories [DEPRECATED] build-workspace [packages...] Builds a temporary dist workspace from the provided packages create-github-app Create new GitHub App in your organization. info Show helpful information for debugging and reporting bugs help [command] display help for command ``` The `package` command category, `yarn backstage-cli package --help`: ```text start [options] Start a package for local development build [options] Build a package for production deployment or publishing lint [options] [directories...] Lint a package test Run tests, forwarding args to Jest, defaulting to watch mode clean Delete cache directories prepack Prepares a package for packaging before publishing postpack Restores the changes made by the prepack command help [command] display help for command ``` The `repo` command category, `yarn backstage-cli repo --help`: ```text start [options] [packageName...] Starts packages in the repo for local development build [options] Build packages in the project, excluding bundled app and backend packages. test [options] Run tests, forwarding args to Jest, defaulting to watch mode lint [options] Lint all packages in the project fix [options] Automatically fix packages in the project clean Delete cache and output directories list-deprecations [options] List deprecations help [command] display help for command ``` The `migrate` command category, `yarn backstage-cli migrate --help`: ```text package-roles Add package role field to packages that don't have it package-scripts Set package scripts according to each package role package-exports Synchronize package subpath export definitions package-lint-configs Migrates all packages to use @backstage/cli/config/eslint-factory react-router-deps Migrates the react-router dependencies for all packages to be peer dependencies help [command] display help for command ``` ## repo start Start a set of packages in the project for local development. If no explicit packages are listed via arguments or options, packages will instead be selected based on their [package role](./02-build-system.md#package-roles). If a single set of frontend and/or backend packages are found, they will be started. If there are multiple matches the directories 'packages/app' and 'packages/backend' will be preferred. If no matches are found the command will fall back to expecting a single plugin frontend and/or backend package to start instead. Any `--config` options in the `start` script in `package.json` of the selected packages will be picked up and used, unless a `--config` option is provided to this command, in which case it will be used instead. Any `--require` option in the `start` script in `package.json` of the selected backend package will be picked up and used. ```text Usage: backstage-cli repo start [options] [packageNameOrPath...] Starts packages in the repo for local development Arguments: packageNameOrPath Run the specified packages instead of the defaults. Options: --plugin Start the dev entry-point for any matching plugin package in the repo (default: []) --config Config files to load instead of app-config.yaml (default: []) --inspect [host] Enable debugger in Node.js environments. Applies to backend package only --inspect-brk [host] Enable debugger in Node.js environments, breaking before code starts. Applies to backend package only --require Add a --require argument to the node process. Applies to backend package only --link Link an external workspace for module resolution ``` ## repo build Builds all packages in the project, excluding bundled packages by default, i.e. ones with the role `'frontend'` or `'backend'`. ```text Usage: backstage-cli repo build [options] Build packages in the project, excluding bundled app and backend packages. Options: --all Build all packages, including bundled app and backend packages. --since Only build packages and their dev dependents that changed since the specified ref ``` ## repo lint Lint all packages in the project. ```text Usage: backstage-cli repo lint [options] Lint all packages in the project Options: --format Lint report output format (default: "eslint-formatter-friendly") --since Only lint packages that changed since the specified ref --success-cache Enable success caching, which skips running lint for unchanged packages that were successful in the previous run --success-cache-dir Set the success cache location, (default: node_modules/.cache/backstage-cli) --fix Attempt to automatically fix violations ``` ## repo test Test packages in the project. It is recommended to have this command be used as the `test` script in the root `package.json` in your project: ```json title="package.json in the root of your project" { ... "scripts": { ... "test": "backstage-cli repo test" } } ``` If run without any arguments it will default to running changed tests in watch mode, unless the `CI` environment flag is set, in which case it will run all tests without watching: ```sh title="Run changes tests from repo root" yarn test ``` If arguments are provided, they will be forwarded to Jest and used to filter test to execute. If full paths to tests are provided, only those tests will be included, for example: ```sh title="Run specific tests from repo root" yarn test packages/app/src/App.test.tsx ``` If you want to avoid re-running tests that have not changed since the last successful run in CI, you can use the `--success-cache` flag. By default this cache is stored in `node_modules/.cache/backstage-cli`, but you can choose a different directory with the `--success-cache-dir `. ```text Usage: backstage-cli repo test [options] Run tests, forwarding args to Jest, defaulting to watch mode Options: --since Only test packages that changed since the specified ref --success-cache Enable success caching, which skips running tests for unchanged packages that were successful in the previous run --success-cache-dir Set the success cache location, (default: node_modules/.cache/backstage-cli) --jest-help Show help for Jest CLI options, which are passed through -h, --help display help for command ``` ## package start Starts the package for local development. See the frontend and backend development parts in the build system [bundling](./02-build-system.md#bundling) section for more details. ```text Usage: backstage-cli package start [options] Start a package for local development Options: --config Config files to load instead of app-config.yaml (default: []) --role Run the command with an explicit package role --check Enable type checking and linting if available --inspect Enable debugger in Node.js environments --inspect-brk Enable debugger in Node.js environments, breaking before code starts --entrypoint Entry directory path (uses index file) or entry file path (without extension). Defaults to "dev" ``` ## package build Build an individual package based on its role. See the build system [building](./02-build-system.md#building) and [bundling](./02-build-system.md#bundling) sections for more details. ```text Usage: backstage-cli package build [options] Build a package for production deployment or publishing Options: --role Run the command with an explicit package role --minify Minify the generated code. Does not apply to app package (app is minified by default). --skip-build-dependencies Skip the automatic building of local dependencies. Applies to backend packages only. --stats If bundle stats are available, write them to the output directory. Applies to app packages only. --config Config files to load instead of app-config.yaml. Applies to app packages only. (default: []) --module-federation Build a package as a module federation remote. Applies to frontend plugin packages only. ``` ## package bundle :::caution Experimental This command is experimental and may receive breaking changes in future releases without a deprecation period. It is hidden from the main `--help` output. ::: Bundle a plugin for dynamic loading. This creates a self-contained plugin package that can be deployed independently and loaded dynamically by a Backstage application. Supports both backend and frontend plugins. Unlike regular builds, the bundle command: - Creates a fully self-contained plugin deliverable - Produces module federation assets (frontend) or includes plugin dependencies in the plugin's private `node_modules`, building and packing (with `yarn pack`) the local `workspace:^` dependencies first (backend). - Generates a config schema from plugin-related packages only. - Validates that the plugin exports valid dynamic loading entry points (backend only) ### Usage ```bash # Bundle the current package (output: ./bundle/) yarn backstage-cli package bundle # Bundle to a specific directory (output: ../dynamic-plugins//) yarn backstage-cli package bundle --output-destination ../dynamic-plugins # Override the bundle subdirectory name yarn backstage-cli package bundle --output-name my-plugin-bundle # Clean output before bundling yarn backstage-cli package bundle --clean # Skip building for the plugin and its local dependencies yarn backstage-cli package bundle --no-build # Skip dependency installation and entrypoint validation yarn backstage-cli package bundle --no-install # Stream detailed output from build, pack, and install steps yarn backstage-cli package bundle --verbose # Use a pre-built dist workspace for batch bundling. # First, create the workspace with: # backstage-cli build-workspace [packages...] --alwaysPack # Then pass as --pre-packed-dir: yarn backstage-cli package bundle --pre-packed-dir ../dist-workspace ``` ### Options ```text Usage: backstage-cli package bundle [options] Bundle a plugin for dynamic loading Options: --output-destination Directory in which the bundle subdirectory is created. Defaults to the current package directory. --output-name Name of the bundle subdirectory. Defaults to "bundle" when output stays in the package directory, or to the mangled package name (e.g. myorg-plugin-foo) when --output-destination is specified. --clean Clean the output directory before bundling --no-build Skip building packages (assumes they are already built) --no-install Skip dependency installation and entrypoint validation. --verbose Stream detailed output from internal steps (build, pack, install) to the console. Without this flag, output is captured to per-step log files and only shown on error. --pre-packed-dir Path to a pre-built dist workspace (from build-workspace --alwaysPack). Skips local dependency packing and uses pre-packed packages directly. For frontend plugins, this also enables yarn.lock generation for SBOM. ``` ### Output Contract The bundle output is a directory that can be deployed as a standalone unit. Consumers of the bundle (such as `@backstage/backend-dynamic-feature-service` or `@backstage/frontend-dynamic-feature-loader`) can rely on the following guarantees: **All bundles:** - A `package.json` at the bundle root with entry points configured for dynamic loading. The `backstage.role` and `files` fields are preserved from the source package. - A `dist/` directory containing the built plugin code. - A `dist/.config-schema.json` file (when any config schemas apply) containing gathered schemas from the plugin, its local workspace dependencies, and third-party dependencies. Schemas from unrelated Backstage packages are excluded. - No `scripts` or `devDependencies` in `package.json`. **Backend plugins** (`backend-plugin`, `backend-plugin-module`): - A `node_modules/` directory with all production dependencies (including local workspace dependencies), pinned to their exact versions from the source lockfile. - `bundleDependencies` is set to `true` in `package.json`. **Frontend plugins** (`frontend-plugin`, `frontend-plugin-module`): - `main` points to `dist/remoteEntry.js` (the Module Federation remote entry). - `types` points to `dist/@mf-types/index.d.ts` when type declarations are available. - No embedded `node_modules/` directory. ### Environment Variables The bundle command supports the same environment variables as the Backstage yarn plugin for resolving `backstage:^` version specifiers: - `BACKSTAGE_MANIFEST_FILE`: Path to a local manifest file (for offline usage) - `BACKSTAGE_VERSIONS_BASE_URL`: Custom base URL for fetching release manifests ### Supported Package Roles The bundle command supports packages with the following roles: - `backend-plugin` - `backend-plugin-module` - `frontend-plugin` - `frontend-plugin-module` ## package lint Lint a package. In addition to the default `eslint` behavior, this command will include TypeScript files, treat warnings as errors, and default to linting the entire directory if no specific files are listed. For more information, see the build system [linting](./02-build-system.md#linting) section. ```text Usage: backstage-cli package lint [options] Lint a package Options: --format Lint report output format (default: "eslint-formatter-friendly") --fix Attempt to automatically fix violations --max-warnings Fail if more than this number of warnings. -1 allows warnings. (default: -1) ``` ## package test Run tests, forwarding all unknown options to Jest, and defaulting to watch mode. When executing the tests, `process.env.NODE_ENV` will be set to `"test"`. This command uses a default Jest configuration that is included in the CLI, which is set up with similar goals for speed, scale, and working within a monorepo. The configuration sets the `src` as the root directory, enforces the `.test.` infix for tests, and uses `src/setupTests.ts` as the test setup location. The included configuration also supports test execution at the root of a yarn workspaces monorepo by automatically creating one grouped configuration that includes all packages that have `backstage-cli test` in their package `test` script. For more information about configuration overrides and editor support, see the [Jest Configuration section](./02-build-system.md#jest-configuration) in the build system documentation. ```text Usage: backstage-cli package test [options] Run tests, forwarding args to Jest, defaulting to watch mode Options: --backstage-cli-help display help for command ``` ## package clean Remove cache and output directories. ```text Usage: backstage-cli package clean [options] Delete cache directories ``` ## package prepack This command should be added as `scripts.prepack` in all packages. It enables packaging- and publish-time overrides for fields inside `packages.json`. For more details, see the build system [publishing](./02-build-system.md#publishing) section. ```text Usage: backstage-cli package prepack [options] Prepares a package for packaging before publishing ``` ## package postpack This should be added as `scripts.postpack` in all packages. It restores `package.json` to what it looked like before calling the `prepack` command. ```text Usage: backstage-cli package postpack [options] Restores the changes made by the prepack command ``` ## new The `new` command opens up an interactive guide for you to create new things in your app. If you do not pass in any options it is completely interactive, but it is possible to pre-select what you want to create using the `--select` flag, and provide options using `--option`, for example: ```bash backstage-cli new --select frontend-plugin --option pluginId=foo ``` This command is typically added as script in the root `package.json` to be executed with `yarn new`. For example you may have it set up like this: ```json { "scripts": { "new": "backstage-cli new" } } ``` The `new` command comes with a default collection of plugins/packages, however, you can customize this list and even create your own CLI templates. For more information see [CLI Templates](./04-templates.md). ```text Usage: backstage-cli new Options: -h, --help display help for command ``` ## config\:docs This commands opens up the reference documentation of your apps local configuration schema in the browser. This is useful to get an overview of what configuration values are available to use, a description of what they do and their format, and where they get sent. ```text Usage: backstage-cli config:docs [options] Browse the configuration reference documentation Options: --package Only include the schema that applies to the given package -h, --help display help for command ``` ## config\:print Print the static configuration, defaulting to reading `app-config.yaml` in the repo root, using schema collected from all local packages in the repo. For example, to validate that a given configuration value is visible in the frontend when building the `my-app` package, you can use the following: ```bash yarn backstage-cli config:print --frontend --package my-app ``` ```text Usage: backstage-cli config:print [options] Options: --package Only load config schema that applies to the given package --lax Do not require environment variables to be set --frontend Print only the frontend configuration --with-secrets Include secrets in the printed configuration --format Format to print the configuration in, either json or yaml [yaml] --config Config files to load instead of app-config.yaml (default: []) -h, --help display help for command ``` ## config\:check Validate that static configuration loads and matches schema, defaulting to reading `app-config.yaml` in the repo root and using schema collected from all local packages in the repo. ```text Usage: backstage-cli config:check [options] Options: --package Only load config schema that applies to the given package --lax Do not require environment variables to be set --frontend Only validate the frontend configuration --deprecated Output deprecated configuration settings --strict Ensure that the provided config(s) has no errors and does not contain keys not in the schema. --config Config files to load instead of app-config.yaml (default: []) -h, --help display help for command ``` ## config\:schema Dump the configuration schema that was collected from all local packages in the repo. Note: when run by `yarn`, supply the yarn option `--silent` if you are using the output in a command line pipe to avoid non schema output in the pipeline. ```text Usage: backstage-cli config:schema [options] Print configuration schema Options: --package Only output config schema that applies to the given package --format Format to print the schema in, either json or yaml [yaml] -h, --help display help for command ``` ## versions\:bump Bump all `@backstage` packages to the latest versions. This checks for updates in the package registry, and will update entries `package.json` files when necessary. See more how this command can be configured and used [for keeping Backstage updated](../../getting-started/keeping-backstage-updated.md). ```text Usage: backstage-cli versions:bump [options] Options: -h, --help display help for command --pattern Override glob for matching packages to upgrade --release Bump to a specific Backstage release line or version (default: "main") ``` ## build-workspace Builds a mirror of the workspace using the packaged production version of each package. This essentially calls `yarn pack` in each included package and unpacks the resulting archive in the target `workspace-dir`. ```text Usage: backstage-cli build-workspace [options] [packages...] Options: --alwaysPack Force workspace output to be a result of running `yarn pack` on each package (warning: very slow) ``` When `--alwaysPack` is used, the output directory can be passed to `backstage-cli package bundle --pre-packed-dir` to speed up batch bundling of multiple plugins from the same monorepo. ## create-github-app Creates a GitHub App in your GitHub organization. This is an alternative to token-based [GitHub integration](../../integrations/github/locations.md). See [GitHub Apps for Backstage Authentication](../../integrations/github/github-apps.md). Launches a browser to create the App through GitHub and saves the result as a YAML file that can be referenced in the GitHub integration configuration. ```text Usage: backstage-cli create-github-app ``` ## translations export Export translation messages from an app and all of its frontend plugins to JSON files. This command must be run from within a package directory (e.g. `packages/app`), not from the repository root. The command discovers all `TranslationRef` definitions in the dependency tree, extracts their default messages using the TypeScript type system, and writes them as JSON files along with a manifest. For more details on the translation workflow, see the [Internationalization](../../plugins/internationalization.md) documentation. ```text Usage: backstage-cli translations export [options] Options: --output Output directory for exported messages and manifest (default: "translations") --pattern File path pattern for message files relative to the output directory, with {id} and {lang} placeholders (default: "messages/{id}.{lang}.json") -h, --help display help for command ``` ### Examples Export translations with default settings: ```bash cd packages/app yarn backstage-cli translations export ``` Export with language-based directory grouping: ```bash yarn backstage-cli translations export --pattern '{lang}/{id}.json' ``` ## translations import Generate translation resource wiring code from translated JSON files. Reads the manifest and translated message files produced by `translations export`, and generates a TypeScript module that creates `TranslationResource` objects for each translated ref. The file pattern used during export is stored in the manifest and automatically used by the import command. ```text Usage: backstage-cli translations import [options] Options: --input Input directory containing the manifest and translated message files (default: "translations") --output Output path for the generated wiring module (default: "src/translations/resources.ts") -h, --help display help for command ``` ### Examples Generate wiring code with default settings: ```bash cd packages/app yarn backstage-cli translations import ``` ## info Outputs debug information which is useful when opening an issue. Outputs system information, node.js and npm versions, CLI version and type (inside backstage repo or a created app), all `@backstage/*` package dependency versions, and any packages that contain a `backstage` field in their `package.json`. The command distinguishes between installed packages (from npm) and local workspace packages, making it easier to understand your Backstage setup. ```text Usage: backstage-cli info [options] Options: --include Glob patterns for additional packages to include (e.g., @mycompany/backstage-*) --format Output format (default: text) -h, --help display help for command ``` ### Examples Output debug information to the console: ```bash yarn backstage-cli info ``` Include additional packages matching a glob pattern: ```bash yarn backstage-cli info --include "@mycompany/*" ``` Output as JSON: ```bash yarn backstage-cli info --format json ``` Export JSON to a file for further processing: ```bash yarn backstage-cli info --format json > backstage-info.json ``` Combine options to include custom packages and export to JSON: ```bash yarn backstage-cli info --include "@mycompany/backstage-*" --include "@internal/*" --format json > debug-info.json ``` Export text output to a file: ```bash yarn backstage-cli info --format text > backstage-info.txt ``` ### JSON Output Format When using `--format json`, the output is structured as follows: ```json { "system": { "os": "Darwin 23.0.0 - darwin/arm64", "node": "v18.17.0", "yarn": "3.6.0", "cli": { "version": "0.27.0", "local": false }, "backstage": "1.20.0" }, "dependencies": { "@backstage/core-plugin-api": "1.8.0", "@backstage/plugin-catalog": "1.15.0" }, "local": { "@mycompany/backstage-plugin-custom": "0.1.0" } } ```