Document CLI version support

docs/api/cli-options.md

@@ -16,7 +16,7 @@ All of the following documentation is available in the CLI by running `storybook
 
 <Callout variant="info" icon="💡">
 
-The commands work slightly differently if you're using npm instead of Yarn to publish Storybook. For example, `npm run storybook build -- -o ./path/to/build`.
+Passing options to these commands works slightly differently if you're using npm instead of Yarn. You must prefix all of your options with `--`. For example, `npm run storybook build -- -o ./path/to/build --quiet`.
 
 </Callout>
 
@@ -112,12 +112,14 @@ Options include:
 
 ### `upgrade`
 
-Upgrades your Storybook instance to the latest version. Read more in the [upgrade guide](../configure/upgrading.md).
+Upgrades your Storybook instance to the specified version (e.g. `@latest`, `@8`, `@next`). Read more in the [upgrade guide](../configure/upgrading.md).
 
 ```shell
-storybook upgrade [options]
+storybook[@version] upgrade [options]
 ```
 
+For example, `storybook@latest upgrade --dry-run` will perform a dry run (no actual changes) of upgrading your project to the latest version of Storybook.
+
 Options include:
 
 | Option               | Description                                                                                                                                                                 |
@@ -179,25 +181,22 @@ Options include:
 
 ### `sandbox`
 
-Generates a local sandbox project for testing Storybook features based on the list of supported [frameworks](../configure/frameworks.md). Useful for reproducing bugs when opening an issue or a discussion.
+Generates a local sandbox project using the specified version (e.g. `@latest`, `@8`, `@next`) for testing Storybook features based on the list of supported [frameworks](../configure/frameworks.md). Useful for reproducing bugs when opening an issue or a discussion.
 
 ```shell
-storybook sandbox [framework-filter] [options]
+storybook[@version] sandbox [framework-filter] [options]
 ```
 
-<Callout variant="info">
-
-The `framework-filter` argument is optional and can filter the list of available frameworks. For example, `storybook sandbox react` will only show React-based sandboxes.
+For example, `storybook@next sandbox react` will only offer to generate React-based sandboxes, using the newest pre-release version of Storybook.
 
-</Callout>
+The `framework-filter` argument is optional and can filter the list of available frameworks.
 
 Options include:
 
-| Option                         | Description                                                                                                                                                                                                                       |
-| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `-b`, `--branch [branch name]` | Select the branch to use for the sandbox project featuring the available features present in the selected branch (`next` for the pre-release version, `main` for the latest stable release)<br/>`storybook sandbox --branch main` |
-| `-o`, `--output [dir-name]`    | Configures the location of the sandbox project<br/>`storybook sandbox --output /my-sandbox-project`                                                                                                                               |
-| `--no-init`                    | Generates a sandbox project without without initializing Storybook<br/>`storybook sandbox --no-init`                                                                                                                              |
+| Option                      | Description                                                                                          |
+| --------------------------- | ---------------------------------------------------------------------------------------------------- |
+| `-o`, `--output [dir-name]` | Configures the location of the sandbox project<br/>`storybook sandbox --output /my-sandbox-project`  |
+| `--no-init`                 | Generates a sandbox project without without initializing Storybook<br/>`storybook sandbox --no-init` |
 
 <Callout variant="info">
 

docs/configure/upgrading.md

@@ -22,10 +22,16 @@ To help ease the pain of keeping Storybook up-to-date, we provide a command-line
 
 <!-- prettier-ignore-end -->
 
+The `upgrade` command will use whichever version you specify. For example:
+
+- `storybook@latest upgrade` will upgrade to the latest version
+- `storybook@7.6.10 upgrade` will upgrade to `7.6.10`
+- `storybook@7 upgrade` will upgrade to the newest `7.x.x` version
+
 After running the command, the script will:
 
-- Upgrade all Storybook packages in your project to the latest stable version
-- Run the relevant [automigrations](../migration-guide.md#automatic-upgrade) factoring in the [breaking changes](../migration-guide.md#major-breaking-changes) between your current version and the latest stable version
+- Upgrade all Storybook packages in your project to the specified version
+- Run the relevant [automigrations](../migration-guide.md#automatic-upgrade) factoring in the [breaking changes](../migration-guide.md#major-breaking-changes) between your current version and the specified version
 
 <Callout variant="info">
 
@@ -85,6 +91,12 @@ To upgrade to the latest pre-release:
 
 <!-- prettier-ignore-end -->
 
+The `upgrade` command will use whichever version you specify. For example:
+
+- `storybook@next upgrade` will upgrade to the newest pre-release version
+- `storybook@8.0.0-beta.1 upgrade` will upgrade to `8.0.0-beta.1`
+- `storybook@8 upgrade` will upgrade to the newest `8.x` version
+
 If you'd like to downgrade to a stable version, manually edit the package version numbers in your `package.json` and re-install.
 
 <Callout variant="info">

docs/get-started/install.md

@@ -16,6 +16,17 @@ Use the Storybook CLI to install it in a single command. Run this inside your pr
 
 <!-- prettier-ignore-end -->
 
+<details>
+<summary>Install a specific version</summary>
+
+The `init` command will use whichever version you specify. For example:
+
+- `storybook@latest init` will initialize the latest version
+- `storybook@7.6.10 init` will initialize `7.6.10`
+- `storybook@7 init` will initialize the newest `7.x.x` version
+
+</details>
+
 Storybook will look into your project's dependencies during its install process and provide you with the best configuration available.
 
 The command above will make the following changes to your local environment:

docs/snippets/common/storybook-upgrade-prerelease.npm.js.mdx

@@ -1,3 +1,3 @@
 ```shell
-npx storybook@latest upgrade --prerelease
+npx storybook@next upgrade
 ```

docs/snippets/common/storybook-upgrade-prerelease.pnpm.js.mdx

@@ -1,3 +1,3 @@
 ```shell
-pnpm dlx storybook@latest upgrade --prerelease
+pnpm dlx storybook@next upgrade
 ```

docs/snippets/common/storybook-upgrade-prerelease.yarn.js.mdx

@@ -1,3 +1,3 @@
 ```shell
-yarn dlx storybook@latest upgrade --prerelease
+yarn dlx storybook@next upgrade
 ```