message: docs/cli: flesh out index page
diff: @@ -6,15 +6,65 @@ description: Overview of the Backstage CLI
  ## Summary
  -Backstage ships its own CLI tooling
  +Backstage provides an opinionated set of tooling for both frontend and backend
  +development. It is delivered through the `@backstage/cli` package and executed
  +either directly through `yarn backstage-cli <command>` or within yarn scripts.
  +When creating an app using `@backstage/create-app` it contains package scripts
  +for executing the most common commands.
  -Tooling both for bundling deployment artifacts, as well as building individual
  -packages for publishing.
  -
  -Under the hook we use [webpack](https://webpack.js.org/) for bundling,
  +Under the hood the CLI uses [webpack](https://webpack.js.org/) for bundling,
  [rollup](https://rollupjs.org/) for building packages,
  [jest](https://jestjs.io/) for testing, and [eslint](https://eslint.org/) for
  -linting.
  +linting. It also includes custom tooling for working within Backstage apps, for
  +example for keeping the app up to date and verifying static configuration.
  +
  +## Introduction
  +
  +A goal of Backstage is to provide a delightful developer experience in and
  +around the project. Creating new apps and plugins should be simple, iteration
  +speed should be fast, and the overhead of maintaining custom tooling should be
  +minimal. As a part of accomplishing this goal, Backstage provides its own set of
  +opinionated tooling, delivered primarily through the `@backstage/cli` package.
  +
  +The `@backstage/cli` package provides a single `bin` script, `backstage-cli`,
  +which you can execute directly with `yarn` or within a script in `package.json`.
  +If you have a Backstage app set up, you can try out the following command to
  +print the top-level help page of the CLI:
  +
  +```bash
  +yarn backstage-cli --help
  +```
  +
  +If you are familiar with `create-react-app` you may recognize this pattern, as
  +it uses a package called `react-scripts` to bring most of the functionality into
  +the created project. The Backstage equivalent of `create-react-app` is
  +`@backstage/create-app`, and the equivalent of `react-scripts` is
  +`@backstage/cli`. There are however a couple of key differences between the two.
  +Most notably, Backstage apps are monorepos and the CLI is tailored for that
  +environment. It provides tooling both for bundling and developing full end-user
  +apps, but also for developing, building and publishing individual packages
  +within the monorepo.
  +
  +## Opinionated
  +
  +The Backstage CLI is highly opinionated in what tools to use and how they are
  +configured. It is tailored for development in large TypeScript monorepos with
  +hundreds of separate plugins, but with the ability to have edits anywhere in the
  +codebase reflected within a few seconds. The build output is also optimized for
  +this setup, and aims for an excellent user experience with fast page load times
  +in modern browsers, rather than a wide range of support.
  +
  +While the Backstage tooling is opinionated in how to develop and build packages,
  +it is also possible to use your own tooling either partially or fully. For
  +example, the CLI provides a command for building a plugin package for
  +publishing, but the output is a pretty regular `types+js` output that you see in
  +many packages, which can easily be achieved with many other sets of tooling.
  +
  +Just like `react-scripts`, the Backstage CLI does not provide many hooks for
  +overriding or customizing the build process. This is to allow for evolution of
  +the CLI without having to take a wide API surface into account. Allowing us to
  +more quickly iterate and improve the tooling, as well more easily keeping
  +dependencies up to date.
  ## Glossary
  