CLI Options

Purpose and Scope

The Storybook command line interface is the day-to-day entry point for running and building a Storybook from a project workspace. The API page describes it as the main tool used to build and develop Storybook, which means readers should treat the CLI as both an operational interface and a reference surface. In practice, this page helps developers answer three recurring questions: which command should I run, where should I run it from, and how do I pass options correctly through the package manager that owns my scripts.

Sources: docs/api/cli-options.mdx

The most important distinction is between Storybook’s own command syntax and the package-manager wrapper around it. When a command is executed directly, options can be passed to the Storybook executable in the usual way. When the same command is invoked through an npm script, npm consumes option-like arguments unless they are separated with an extra delimiter. The official reference calls this out because it is a common source of confusing behavior in local development and continuous integration. Yarn users usually pass the options after the script command, while npm users must add the delimiter before Storybook-specific flags.

Sources: docs/api/cli-options.mdx

The CLI reference also includes an explicit privacy signal. Storybook collects completely anonymous data to improve user experience, but participation is optional and users can opt out. That note belongs in a CLI reference because command execution is one of the places where developers first encounter project-wide behavior that is not directly tied to rendering a story. Teams with strict governance requirements should review telemetry decisions while they are standardizing their Storybook scripts, ports, hosts, and build commands, so local development and automated environments behave predictably.

Sources: docs/api/cli-options.mdx

Relevant Source Files

• docs/api/cli-options.mdx: Defines the public documentation page for Storybook CLI options, including the page metadata, telemetry callout, the shared command-help convention, npm option forwarding guidance, and the visible dev command option table.

Command Model

The CLI page organizes commands as named subcommands with command-specific option sets. The visible command is the development server command, written as a command followed by optional flags. The documented form is concise, but it carries several assumptions: the command is run from the root of the project, it compiles a development build, it serves that build in the browser, and it reflects source-code changes in real time. In other words, it is the command used while authoring stories, debugging component states, reviewing addon behavior, and checking documentation pages interactively.

Sources: docs/api/cli-options.mdx

The installed CLI is also self-documenting. The documentation states that the command reference is available by running the help command from the installed Storybook CLI. That is useful because CLI surfaces can vary by Storybook version, project framework, and installed packages. A team should keep the docs page as the conceptual reference, but use local help output as the final authority for the package version that is actually installed in the repository. This is especially important during upgrades, when a script may continue to exist while individual flags or defaults change.

Sources: docs/api/cli-options.mdx

storybook --help
storybook dev [options]

For package scripts, preserve the difference between the script runner and Storybook itself. If a package script invokes Storybook and the package manager is npm, Storybook flags must come after the delimiter. The documentation gives a build-oriented example that passes an output directory and quiet mode to the Storybook build command. That example is not just a syntax footnote; it is a reliable pattern for continuous integration commands, publish scripts, and documentation builds where a flag silently being swallowed by npm can produce output in the wrong location or with the wrong logging level.

Sources: docs/api/cli-options.mdx

npm run storybook build -- -o ./path/to/build --quiet

Development Server Reference

The documented development command compiles and serves a live development build of Storybook. It should be run from the project root, because Storybook needs to discover the project’s package metadata, configuration directory, framework integration, addons, stories, and builder configuration relative to that root. Running from another directory can make a command appear valid while causing configuration discovery to point at the wrong place. When diagnosing an unexpected configuration result, first confirm the working directory, then confirm the config directory, and only then inspect framework or builder options.

Sources: docs/api/cli-options.mdx

The server address is controlled by port and host flags. The port flag chooses where the local Storybook server listens, and the exact-port flag changes fallback behavior. Without an exact-port requirement, development tools often try to help by moving to another available port. With exact-port enabled, Storybook exits with an error if the requested port is already in use. That stricter behavior is useful for scripts, screenshots, reverse proxies, and tools that expect a stable endpoint. It is less forgiving during ad hoc local development, where automatic port selection can reduce friction.

Sources: docs/api/cli-options.mdx

The host option controls which network interface receives traffic. The documentation notes that setting the host to all interfaces can expose the development Storybook beyond the loopback interface, which is useful for testing on devices, virtual machines, or containerized environments. That same setting should be considered together with allowed-host restrictions in core configuration. A host flag decides where the server binds; allowed-host configuration decides which hostnames may access the instance. Treat them as complementary controls rather than alternatives, especially when a development server is reachable from a shared network.

Sources: docs/api/cli-options.mdx

Logging and transport options shape the development experience but also affect debugging. The loglevel option accepts a defined set of levels, with normal informational output as the default. Lower-noise modes can make CI logs easier to read, while trace or debug output can expose the sequence of configuration and build steps when a project fails to start. HTTPS mode serves Storybook over secure transport, but the documentation explicitly warns that certificate information must be supplied by the user. That matters for browser APIs, secure-cookie behavior, and integrations that require a secure origin during development.

Sources: docs/api/cli-options.mdx

Compact Option Reference

Execution Flow

A practical local workflow starts by confirming the installed CLI and available commands, then running the development server from the project root. If the project uses a standard configuration directory, no directory flag is needed. If the repository contains multiple Storybook configurations, examples, or package-level workspaces, the config-directory flag makes the target explicit. Once the server starts, the browser reflects story and source changes in real time. If startup fails, the first diagnostic checks should be port availability, current directory, configuration directory, and loglevel.

Sources: docs/api/cli-options.mdx

A production or sharing workflow uses the same option-passing principles but usually targets a build command rather than the live server. The visible documentation example demonstrates passing build options through npm, including an output directory and quiet mode. That pattern is important for publishing static Storybooks, embedding generated output into another site, or producing documentation artifacts in CI. If a script works with Yarn but not npm, inspect the placement of the delimiter before assuming the Storybook command is wrong. The wrapper syntax is often the actual difference.

Sources: docs/api/cli-options.mdx

Upgrade and creation workflows should use the CLI page as a command-line contract reference, not as a substitute for the installation and migration guides. The option conventions documented here still apply when creating, initializing, or upgrading a Storybook project: run help for the installed version, pass options after the package-manager delimiter when required, and prefer explicit flags in automation. During upgrades, compare the local help output with the scripts already committed to the project, because old scripts can continue to run while relying on defaults that have changed across major versions.

Sources: docs/api/cli-options.mdx

Edge Cases and Next Steps

The most common edge case is a command that appears to ignore a flag. For npm scripts, the first thing to check is whether the delimiter was included before Storybook options. The second common edge case is a port mismatch: the command may have selected another available port unless exact-port was requested. The third is network exposure: binding to all interfaces can be convenient, but it should be paired with access restrictions when the Storybook instance is reachable beyond a developer’s machine. These issues are configuration problems, not story-authoring problems.

Sources: docs/api/cli-options.mdx

After standardizing local commands, document them in the project’s package scripts and CI configuration so contributors do not have to remember raw command details. Use the development command for interactive authoring, the build command pattern for static artifacts, the help command for version-specific confirmation, and the telemetry configuration guidance for policy decisions. From here, readers usually continue to the install and setup pages for project creation, the builder pages for Vite or Webpack behavior, the build documentation page for static output, and the upgrading page for migration-specific command changes.

Sources: docs/api/cli-options.mdx