docs/cli: flesh out index page

docs/cli/index.md

@@ -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