docs/cli: detailed descriptions for all commands

docs/cli/commands.md

@@ -159,8 +159,38 @@ Options:
 
 ## backend:build-image
 
-Bundles the package into a docker image. All extra args are forwarded to
-`docker image build`.
+Builds a Docker image of the backend package and forwards all unknown options to
+`docker image build`. For example:
+
+```bash
+yarn backstage-cli backend:build-image --build --tag my-backend-image
+```
+
+The image is built with the backend package along with all of its local package
+dependencies. This uses a `Dockerfile` that is expected to exist at the root of
+the backend package. The `Dockerfile` will end up being executed from the root
+of the monorepo, rather than the backend package itself.
+
+The Dockerfile is **NOT** executed within the package or repo itself. Because
+the packages in the repo itself are configured for development instead of
+production use, the final Docker build happens in a separate temporary
+directory, to which the backend package and dependencies have been copied over.
+Only files listed within the `"files"` field within each package's
+`package.json` are copied over, along with the root `package.json`, `yarn.lock`,
+and any `app-config.*.yaml` files.
+
+During the build a `skeleton.tar` file is created and put at the repo root. This
+file contains the `package.json` of each included package, which together with
+the root `package.json` and `yarn.lock` can be used to run a cached
+`yarn install` before the full production builds of all the packages are copied
+over, providing a significant speedup if Docker build layer caching available.
+
+This command is experimental and we hope to be able to replace it with one that
+is less integrated directly with Docker, and also supports multi-stage Docker
+builds. It is possible to replicate most of what this command does by manually
+building each package, then use the `build-workspace` to create the temporary
+workspace, and finally copy over any additional files to the workspace and
+execute the Docker build within it.
 
 ```text
 Usage: backstage-cli backend:build-image [options]
@@ -172,7 +202,8 @@ Options:
 
 ## backend:dev
 
-Start local development server with HMR for the backend
+Starts a backend package in development mode, with watch mode enabled for all
+local packages.
 
 ```text
 Usage: backstage-cli backend:dev [options]
@@ -186,7 +217,10 @@ Options:
 
 ## create-plugin
 
-Creates a new plugin in the current repository
+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
+recommended scope for internal packages is `@internal`.
 
 ```text
 Usage: backstage-cli create-plugin [options]
@@ -201,7 +235,11 @@ Options:
 
 ## remove-plugin
 
-Removes plugin in the current repository
+A utility to remove a plugin from a repo, essentially undoing everything that
+was done by `create-plugin`.
+
+This is primarily intended as a utility for manual tests and end to end testing
+scripts.
 
 ```text
 Usage: backstage-cli remove-plugin [options]
@@ -212,7 +250,15 @@ Options:
 
 ## plugin:build
 
-Build a 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
+when bundling local package dependencies.
+
+The output is written to a `dist/` folder. It also outputs type declarations for
+the plugin, and therefore requires `yarn tsc` to have been run first. The input
+type declarations are expected to be found within `dist-types` at the root of
+the monorepo.
 
 ```text
 Usage: backstage-cli plugin:build [options]
@@ -223,7 +269,13 @@ Options:
 
 ## plugin:serve
 
-Serves the dev/ folder of a 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.
+
+The `dev/` folder typically contains a small wrapper script that hooks up any
+necessary mock APIs or other things that are needed for the plugin to function.
+The `@backstage/dev-utils` package provides utilities to that end.
 
 ```text
 Usage: backstage-cli plugin:serve [options]
@@ -236,7 +288,10 @@ Options:
 
 ## plugin:diff
 
-Diff an existing plugin with the creation template
+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
+project.
 
 ```text
 Usage: backstage-cli plugin:diff [options]
@@ -249,7 +304,15 @@ Options:
 
 ## build
 
-Build a package for publishing
+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
+usage in both the frontend and backend.
+
+For frontend packages you'll want to include `esm` output, and for backend
+packages `cjs`. Whether to include `types` depends on if you need type
+declarations for the package, and also requires `yarn tsc` to have been run
+first.
 
 ```text
 Usage: backstage-cli build [options]
@@ -261,7 +324,9 @@ Options:
 
 ## lint
 
-Lint a package
+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.
 
 ```text
 Usage: backstage-cli lint [options]
@@ -274,7 +339,7 @@ Options:
 
 ## test
 
-Run tests, forwarding args to Jest, defaulting to watch mode
+Run tests, forwarding all unknown options to Jest, and defaulting to watch mode.
 
 ```text
 Usage: backstage-cli test [options]
@@ -285,7 +350,15 @@ Options:
 
 ## config:print
 
-Print the app configuration for the current package
+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]
@@ -301,7 +374,9 @@ Options:
 
 ## config:check
 
-Validate that the given configuration loads and matches schema
+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]
@@ -314,7 +389,9 @@ Options:
 
 ## versions:bump
 
-Bump Backstage packages to the latest versions
+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.
 
 ```text
 Usage: backstage-cli versions:bump [options]
@@ -325,7 +402,14 @@ Options:
 
 ## versions:check
 
-Check Backstage package versioning
+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
+of it installed will cause this command to exit with an error.
+
+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]
@@ -337,7 +421,20 @@ Options:
 
 ## prepack
 
-Prepares a package for packaging before publishing
+This command should be added as `scripts.prepack` in all packages. It enables
+packaging- and publish-time overrides for fields inside `packages.json`.
+
+The checked in version of all packages in a Backstage monorepo are tailored for
+local development, and as such `main` and similar fields inside `package.json`
+point to development source, i.e. `src/index.ts`. Using this when publishing
+would lead to a broken package, since `src/` is not included in the published
+package and we instead need to point to files in the `dist/` directory. This
+command allows for those fields to be rewritten when needed, and does so by
+copying all fields within `publishConfig` to the top-level of each
+`package.json`, skipping `access`, `registry`, and `tag`.
+
+The need for this command may be removed in the future, as this exact method of
+overriding fields for publishing is already supported by some package managers.
 
 ```text
 Usage: backstage-cli prepack [options]
@@ -348,7 +445,8 @@ Options:
 
 ## postpack
 
-Restores the changes made by the prepack command
+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.
 
 ```text
 Usage: backstage-cli postpack [options]
@@ -359,7 +457,7 @@ Options:
 
 ## clean
 
-Delete cache directories
+Remove cache and output directories.
 
 ```text
 Usage: backstage-cli clean [options]
@@ -370,7 +468,9 @@ Options:
 
 ## build-workspace
 
-Builds a temporary dist workspace from the provided packages
+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>