diff --git a/docs/cli/commands.md b/docs/cli/commands.md index 8f8cb74ed7..5fc9608ff0 100644 --- a/docs/cli/commands.md +++ b/docs/cli/commands.md @@ -4,44 +4,61 @@ title: Commands description: Descriptions of all commands available in the CLI. --- -## Summary +This page lists all commands provided by the Backstage CLI, what they're for, +and where to use them. + +The documentation for each command begins with specifying its scope, this +indicates where the command should be used by selecting from the following list: + +- `app` - A frontend app package, such as `packages/app`. +- `backend` - A backend package, such as `packages/backend`. +- `frontend-plugin` - A frontend plugin package. +- `backend-plugin` - A backend plugin package. +- `any` - Any kind of package. +- `root` - The monorepo root, not specific to any one package. + +## help + +The following is a cleaned up output of of `yarn backstage-cli --help`: ```text -app:build [options] Build an app for a production release -app:diff [options] Diff an existing app with the creation template -app:serve [options] Serve an app for local development +app:build Build an app for a production release +app:diff Diff an existing app with the creation template +app:serve Serve an app for local development -backend:build Build a backend plugin -backend:build-image [options] Bundles the package into a docker image. All extra args are forwarded to `docker image build`. -backend:dev [options] Start local development server with HMR for the backend +backend:build Build a backend plugin +backend:build-image Bundles the package into a docker image +backend:dev Start local development server with HMR for the backend -plugin:build Build a plugin -plugin:diff [options] Diff an existing plugin with the creation template -plugin:serve [options] Serves the dev/ folder of a plugin +plugin:build Build a plugin +plugin:diff Diff an existing plugin with the creation template +plugin:serve Serves the dev/ folder of a plugin -build [options] Build a package for publishing -build-workspace Builds a temporary dist workspace from the provided packages -lint [options] Lint a package -test Run tests, forwarding args to Jest, defaulting to watch mode -clean Delete cache directories +build Build a package for publishing +build-workspace Builds a temporary dist workspace from the provided packages +lint Lint a package +test Run tests, forwarding args to Jest, defaulting to watch mode +clean Delete cache directories -create-plugin [options] Creates a new plugin in the current repository -remove-plugin Removes plugin in the current repository +create-plugin Creates a new plugin in the current repository +remove-plugin Removes plugin in the current repository -config:print [options] Print the app configuration for the current package -config:check [options] Validate that the given configuration loads and matches schema +config:print Print the app configuration for the current package +config:check Validate that the given configuration loads and matches schema -versions:bump Bump Backstage packages to the latest versions -versions:check [options] Check Backstage package versioning +versions:bump Bump Backstage packages to the latest versions +versions:check Check Backstage package versioning -prepack Prepares a package for packaging before publishing -postpack Restores the changes made by the prepack command +prepack Prepares a package for packaging before publishing +postpack Restores the changes made by the prepack command -help [command] display help for command +help [command] display help for command ``` ## app:build +Scope: `app` + Creates a bundle of static content from the app, which can then be served via and static web server such as `nginx`, or via the `app-backend` plugin directly from a Backstage backend instance. @@ -81,7 +98,7 @@ can manually limit the parallelization of the build process by setting the environment variable `BACKSTAGE_CLI_BUILD_PARALLEL` to for example `2`. ```text -Usage: backstage-cli app:build [options] +Usage: backstage-cli app:build Options: --stats Write bundle stats to output directory @@ -91,6 +108,8 @@ Options: ## app:diff +Scope: `app` + Diff an existing app with the template used in `@backstage/create-app`. This will verify that your app package has not diverged from the template, and can be useful to run after updating the version of `@backstage/cli` in your app. @@ -100,7 +119,7 @@ This command is experimental and may be removed in the future. Compared to the checks to carry out. ```text -Usage: backstage-cli app:diff [options] +Usage: backstage-cli app:diff Options: --check Fail if changes are required @@ -110,17 +129,13 @@ Options: ## app:serve +Scope: `app` + Serve an app for local development. This starts up a local development server, using a bundling config that is quite similar to the `app:build` command, but with development features such as React Hot Module Replacement, faster sourcemaps, no minification, etc. -The serve configuration is controlled through the static configuration, by -default in `app-config.yaml`. The schema in the `app.baseUrl` determines whether -HTTP or HTTPS is used, and the listening host and port port is also determined -from the URL. It is possible to explicitly override the listening host and port -if needed by setting `app.listen.host` and `app.listen.port`. - The static configuration is injected into the frontend as well, but there it does not support watching, meaning that changes in for example `app-config.yaml` are not reflected until the serve process is restarted. @@ -132,7 +147,11 @@ process.env.NODE_ENV = 'development'; process.env.BUILD_INFO = { /* See app:build */ }; ``` -By default the +The serve configuration is controlled through the static configuration, by +default in `app-config.yaml`. The protocol of `app.baseUrl` determines whether +HTTP or HTTPS is used, and the listening host and port is also determined by the +URL. It is possible to override the listening host and port if needed by setting +`app.listen.host` and `app.listen.port`. ```text Usage: backstage-cli app:serve [options] @@ -145,10 +164,13 @@ Options: ## backend:build -This builds a backend package for publish and use in production. The build +Scope: `backend`, `backend-plugin` (To be replaced by `backend:bundle` for +`backend`) + +This builds a backend package for publishing and use in production. The build output is written to `dist/`. Be sure to list any additional file that the package depends on at runtime in the `"files"` field inside `package.json`, a -common example being the `migrations/` directory. +common example being the `migrations` directory. ```text Usage: backstage-cli backend:build [options] @@ -159,6 +181,8 @@ Options: ## backend:build-image +Scope: `backend` + Builds a Docker image of the backend package and forwards all unknown options to `docker image build`. For example: @@ -202,6 +226,8 @@ Options: ## backend:dev +Scope: `backend`, `backend-plugin` + Starts a backend package in development mode, with watch mode enabled for all local packages. @@ -217,6 +243,8 @@ Options: ## create-plugin +Scope: `root` + Creates a new plugin within the repository. This command is typically wrapped up in the root `package.json` to be executed with `yarn create-plugin`, using options that are appropriate for the organization that owns the app repo. A @@ -235,6 +263,8 @@ Options: ## remove-plugin +Scope: `root` + A utility to remove a plugin from a repo, essentially undoing everything that was done by `create-plugin`. @@ -250,6 +280,8 @@ Options: ## plugin:build +Scope: `frontend-plugin` + Build a frontend plugin for publishing to a package registry. There is no need to run this command during development or even in CI unless the package is being published. The `app:bundle` command does not use the output for this command @@ -269,6 +301,8 @@ Options: ## plugin:serve +Scope: `frontend-plugin` + Serves a frontend plugin by itself for isolated development. The serve task itself is essentially identical to `app:serve`, but the entrypoint is instead set to the `dev/` folder within the plugin. @@ -288,6 +322,8 @@ Options: ## plugin:diff +Scope: `frontend-plugin` + Compares a frontend plugin to the `create-plugin` template, making sure that it hasn't diverged from the template and recommending updates when it has. A good practice is to run this command after updating the version of the CLI in a @@ -304,6 +340,8 @@ Options: ## build +Scope: `any` + Build a single package for publishing, just like the `plugin:build` and `backend:build` commands. This command is intended for standalone packages that aren't plugins, and for example support building of isomorphic packages for @@ -324,6 +362,8 @@ Options: ## lint +Scope: `any` + 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 of no specific files are listed. @@ -339,6 +379,8 @@ Options: ## test +Scope: `any` + Run tests, forwarding all unknown options to Jest, and defaulting to watch mode. ```text @@ -350,6 +392,8 @@ Options: ## config:print +Scope: `root` + Print the static configuration, defaulting to reading `app-config.yaml` in the repo root, using schema collected from all local packages in the repo. @@ -374,6 +418,8 @@ Options: ## config:check +Scope: `root` + 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. @@ -389,6 +435,8 @@ Options: ## versions:bump +Scope: `root` + Bump all `@backstage` packages to the latest versions. This check for updates in the package registry, and will update entries both in `yarn.lock` and `package.json` files when necessary. @@ -402,6 +450,8 @@ Options: ## versions:check +Scope: `root` + Validate `@backstage` dependencies within the repo, making sure that there are no duplicates of packages that might lead to breakages. For example, `@backstage/core` must not be loaded in twice, so having two different versions @@ -421,6 +471,8 @@ Options: ## prepack +Scope: `any` + This command should be added as `scripts.prepack` in all packages. It enables packaging- and publish-time overrides for fields inside `packages.json`. @@ -445,6 +497,8 @@ Options: ## postpack +Scope: `any` + This should be added as `scripts.postpack` in all packages.return. It restores `package.json` to what it looked like before calling the `prepack` command. @@ -457,6 +511,8 @@ Options: ## clean +Scope: `any` + Remove cache and output directories. ```text @@ -468,6 +524,8 @@ Options: ## build-workspace +Scope: `any` + 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`.