Project: Backstage (App Definition and Development / Application Definition & Image Build)
File: cli-commands.md

id: cli-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. 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 test Run tests, forwarding args to Jest, defaulting to watch mode [DEPRECATED] 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 versions:check [options] Check Backstage package versioning clean Delete cache directories [DEPRECATED] build-workspace <workspace-dir> [packages...] Builds a temporary dist workspace from the provided packages create-github-app <github-org> 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 build [options] Build packages in the project, excluding bundled app and backend packages. lint [options] Lint all packages in the project clean Delete cache and output directories list-deprecations [options] List deprecations test [options] Run tests, forwarding args to Jest, defaulting to watch mode 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 ``` 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

--since <ref> Only build packages and their dev dependents that changed since the specified ref ``` Lint all packages in the project. ```text Usage: backstage-cli repo lint [options] Lint all packages in the project Options: --format <format> Lint report output format (default: "eslint-formatter-friendly") --since <ref> Only lint packages that changed since the specified ref --fix Attempt to automatically fix violations ``` Starts the package for local development. See the frontend and backend development parts in the build system section for more details. ```text Usage: backstage-cli package start [options] Start a package for local development Options: --config <path> Config files to load instead of app-config.yaml (default: []) --role <name> 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 ``` Build an individual package based on its role. See the build system and sections for more details. ```text Usage: backstage-cli package build [options] Build a package for production deployment or publishing Options: --role <name> 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 <path> Config files to load instead of app-config.yaml. Applies to app packages only. (default: []) ``` 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 section. ```text Usage: backstage-cli package lint [options] Lint a package Options: --format <format> Lint report output format (default: "eslint-formatter-friendly") --fix Attempt to automatically fix violations ``` 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 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 ``` Remove cache and output

```text Usage: backstage-cli package clean [options] Delete cache directories ``` 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 section. ```text Usage: backstage-cli package prepack [options] Prepares a package for packaging before publishing ``` 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 ``` 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 plugin --option id=foo ``` This command is typically added as script in the root `package.json` to be executed with `yarn new`, using options that are appropriate for the organization that owns the app repo. For example you may have it set up like this: ```json { "scripts": { "new": "backstage-cli new --scope internal --no-private --npm-registry https://acme.org/npm" } } ``` ```text Usage: backstage-cli create [options] Options: --select <name> Select the thing you want to be creating upfront --option <name>=<value> Pre-fill options for the creation process (default: []) --scope <scope> The scope to use for new packages --npm-registry <URL> The package registry to use for new packages --no-private Do not mark new packages as private -h, --help display help for command ``` 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 <name> Only include the schema that applies to the given package -h, --help display help for command ``` 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 <name> 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> Format to print the configuration in, either json or yaml [yaml] --config <path> Config files to load instead of

(default: []) -h, --help display help for command ``` 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 <name> 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 <path> Config files to load instead of app-config.yaml (default: []) -h, --help display help for command ``` 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 <name> Only output config schema that applies to the given package --format <format> Format to print the schema in, either json or yaml [yaml] -h, --help display help for command ``` Bump all `@backstage` packages to the latest versions. This checks for updates in the package registry, and will update entries both in `yarn.lock` and `package.json` files when necessary. ```text Usage: backstage-cli versions:bump [options] Options: -h, --help display help for command --pattern <glob> Override glob for matching packages to upgrade --release <version|next|main> Bump to a specific Backstage release line or version (default: "main") ``` Validate `@backstage` dependencies within the repo, making sure that there are no duplicates of packages that might lead to breakages. By supplying the `--fix` flag the command will attempt to fix any conflict that can be resolved by editing `yarn.lock`, but will not attempt to search for remote updates or modify any `package.json` files. ```text Usage: backstage-cli versions:check [options] Options: --fix Fix any auto-fixable versioning problems -h, --help display help for command ``` 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] <workspace-dir> ``` Creates a GitHub App in your GitHub organization. This is an alternative to token-based . See . 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 <github-org> ``` 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. ```text Usage: backstage-cli info ```