Merge pull request #25658 from storybookjs/docs-cli-versioning

Docs: 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>
 
@@ -84,12 +84,14 @@ Options include:
 
 ### `init`
 
-Installs Storybook into your project per specified version (e.g., `@latest`, `@next`). Read more in the [installation guide](../get-started/install.md).
+Installs and initializes the specified version (e.g., `@latest`, `@8`, `@next`) of Storybook into your project. Read more in the [installation guide](../get-started/install.md).
 
 ```shell
 storybook[@version] init [options]
 ```
 
+For example, `storybook@latest init` will install the latest version of Storybook into your project.
+
 Options include:
 
 | Option                 | Description                                                                                                                                                                    |
@@ -133,12 +135,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                                                                                                                                                                 |
@@ -203,17 +207,15 @@ Storybook Environment Info:
 
 ### `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">
+For example, `storybook@next sandbox` will generated sandboxes using the newest pre-release version of Storybook.
 
-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.
-
-</Callout>
+The `framework-filter` argument is optional and can filter the list of available frameworks. For example, `storybook@next sandbox react` will only offer to generate React-based sandboxes.
 
 Options include:
 

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
+- `[email protected] 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
+- `[email protected] 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
+- `[email protected] 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
 ```