0
# Storybook CLI
1
2
Storybook CLI is the command-line interface tool that serves as the easiest way to add Storybook to any project. It provides essential commands for initializing Storybook in existing projects, adding and registering addons, printing system information for bug reports, upgrading to newer versions, and running codemods for migrations. The CLI is designed to be framework-agnostic and works across different frontend technologies, offering a streamlined experience for developers to set up and manage their UI component development environment.
3
4
## Package Information
5
6
- **Package Name**: @storybook/cli
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @storybook/cli`
10
11
## Core Imports
12
13
The package is primarily CLI-focused with an empty main export. Most functionality is accessed through the CLI binary:
14
15
```bash
16
# Using via npx (recommended)
17
npx storybook@latest <command>
18
19
# Or after global installation
20
storybook <command>
21
```
22
23
For rare programmatic usage:
24
25
```typescript
26
import { add, upgrade, migrate } from "@storybook/cli";
27
```
28
29
## Basic Usage
30
31
```bash
32
# Initialize Storybook in an existing project
33
npx storybook@latest init
34
35
# Start development server (most common daily command)
36
storybook dev
37
38
# Build for production
39
storybook build
40
41
# Add an addon to your Storybook
42
npx storybook add @storybook/addon-docs
43
44
# Upgrade Storybook to the latest version
45
npx storybook upgrade
46
47
# Get system information for debugging
48
npx storybook info
49
50
# Run automigrations to fix compatibility issues
51
npx storybook automigrate
52
53
# Check for known problems
54
npx storybook doctor
55
```
56
57
## Architecture
58
59
Storybook CLI is built around several key components:
60
61
- **Command System**: Built with Commander.js providing structured CLI commands with comprehensive options
62
- **Project Detection**: Automatically detects project type and framework to provide appropriate Storybook configuration
63
- **Package Management**: Integrates with npm, yarn, pnpm, and bun for dependency management
64
- **Automigration Engine**: Sophisticated system for upgrading and migrating Storybook projects with automated fixes
65
- **Multi-project Support**: Handles monorepos and multiple Storybook instances
66
- **Template System**: Extensive sandbox templates for different frameworks and configurations
67
68
## Capabilities
69
70
### Project Initialization
71
72
Initialize Storybook in existing projects with automatic framework detection and configuration.
73
74
```bash { .api }
75
storybook init [options]
76
77
Options:
78
-f, --force Force add Storybook
79
-s, --skip-install Skip installing deps
80
--package-manager <npm|pnpm|yarn1|yarn2> Force package manager for installing deps
81
--use-pnp Enable PnP mode for Yarn 2+
82
-p, --parser <babel|babylon|flow|ts|tsx> jscodeshift parser
83
-t, --type <type> Add Storybook for a specific project type
84
-y, --yes Answer yes to all prompts
85
-b, --builder <webpack5|vite> Builder library
86
-l, --linkable Prepare installation for link (contributor helper)
87
--dev/--no-dev Launch/skip development server after initialization
88
```
89
90
[Project Initialization](./initialization.md)
91
92
### Core Commands
93
94
Essential daily-use commands for developing and building Storybook projects from the core package.
95
96
```bash { .api }
97
storybook dev [options] # Start development server
98
storybook build [options] # Build for production
99
storybook index [options] # Generate story index
100
101
# Common dev options
102
storybook dev --port 6006 --host localhost
103
storybook dev --https --ssl-cert ./cert.pem --ssl-key ./key.pem
104
105
# Common build options
106
storybook build --output-dir ./dist/storybook
107
storybook build --docs
108
```
109
110
[Core Commands](./core-commands.md)
111
112
### Addon Management
113
114
Add, remove, and manage Storybook addons with automatic configuration and dependency handling.
115
116
```bash { .api }
117
storybook add <addon> [options]
118
storybook remove <addon> [options]
119
120
Add Options:
121
--package-manager <npm|pnpm|yarn1|yarn2|bun> Force package manager
122
-c, --config-dir <dir-name> Directory where to load Storybook configurations from
123
--skip-install Skip installing deps
124
-s, --skip-postinstall Skip package specific postinstall config modifications
125
-y, --yes Skip prompting the user
126
--skip-doctor Skip doctor check
127
128
Remove Options:
129
--package-manager <npm|pnpm|yarn1|yarn2|bun> Force package manager
130
-c, --config-dir <dir-name> Directory where to load Storybook configurations from
131
-s, --skip-install Skip installing deps
132
```
133
134
[Addon Management](./addon-management.md)
135
136
### Version Management
137
138
Upgrade Storybook packages to newer versions with compatibility checks and automigrations.
139
140
```bash { .api }
141
storybook upgrade [options]
142
143
Options:
144
--package-manager <npm|pnpm|yarn1|yarn2|bun> Force package manager
145
-y, --yes Skip prompting the user
146
-f, --force Force the upgrade, skipping autoblockers
147
-n, --dry-run Only check for upgrades, do not install
148
-s, --skip-check Skip postinstall version and automigration checks
149
-c, --config-dir <dir-name...> Directory(ies) where to load Storybook configurations from
150
```
151
152
[Version Management](./version-management.md)
153
154
### Code Migration
155
156
Run Storybook codemods to migrate source files between versions and configurations.
157
158
```bash { .api }
159
storybook migrate [migration] [options]
160
161
Options:
162
-l, --list List available migrations
163
-g, --glob <glob> Glob for files upon which to apply the migration
164
-p, --parser <babel|babylon|flow|ts|tsx> jscodeshift parser
165
-c, --config-dir <dir-name> Directory where to load Storybook configurations from
166
-n, --dry-run Dry run: verify the migration exists and show the files to which it will be applied
167
-r, --rename <from-to> Rename suffix of matching files after codemod has been applied
168
```
169
170
[Code Migration](./code-migration.md)
171
172
### Automigration System
173
174
Detect and automatically fix compatibility issues, deprecated patterns, and configuration problems.
175
176
```bash { .api }
177
storybook automigrate [fixId] [options]
178
179
Options:
180
-y, --yes Skip prompting the user
181
-n, --dry-run Only check for fixes, do not actually run them
182
--package-manager <npm|pnpm|yarn1|yarn2|bun> Force package manager
183
-l, --list List available migrations
184
-c, --config-dir <dir-name> Directory of Storybook configurations to migrate
185
-s, --skip-install Skip installing deps
186
--renderer <renderer-pkg-name> The renderer package for the framework Storybook is using
187
--skip-doctor Skip doctor check
188
```
189
190
[Automigration System](./automigration.md)
191
192
### Project Diagnostics
193
194
Check Storybook installations for known problems and provide suggestions or fixes.
195
196
```bash { .api }
197
storybook doctor [options]
198
storybook info
199
200
Doctor Options:
201
--package-manager <npm|pnpm|yarn1|yarn2|bun> Force package manager
202
-c, --config-dir <dir-name> Directory of Storybook configuration
203
```
204
205
[Project Diagnostics](./diagnostics.md)
206
207
### Development Tools
208
209
Create sandbox environments, link repositories, and manage development workflows.
210
211
```bash { .api }
212
storybook sandbox [filterValue] [options]
213
storybook link <repo-url-or-directory> [options]
214
215
Sandbox Options:
216
-o, --output <outDir> Define an output directory
217
--no-init Whether to download a template without an initialized Storybook
218
219
Link Options:
220
--local Link a local directory already in your file system
221
--no-start Start the storybook
222
```
223
224
[Development Tools](./development-tools.md)
225
226
## Global Options
227
228
All commands support these global options:
229
230
```bash { .api }
231
Global Options:
232
--disable-telemetry Disable sending telemetry data
233
--debug Get more logs in debug mode
234
--enable-crash-reports Enable sending crash reports to telemetry data
235
--write-logs Write all debug logs to a file at the end of the run
236
--loglevel <trace|debug|info|warn|error|silent> Define log level (default: "info")
237
```
238
239
## Programmatic API (Limited)
240
241
While primarily a CLI tool, some functions are available for programmatic use:
242
243
```typescript { .api }
244
import { add, upgrade, migrate, sandbox, link, doctor } from "@storybook/cli";
245
246
// Add addon programmatically
247
function add(addon: string, options: PostinstallOptions): Promise<void>;
248
249
// Upgrade Storybook programmatically
250
function upgrade(options: UpgradeOptions): Promise<void>;
251
252
// Run migrations programmatically
253
function migrate(migration: string, options: CLIOptions): Promise<void>;
254
255
// Create sandbox programmatically
256
function sandbox(options: SandboxOptions): Promise<void>;
257
258
// Link repositories programmatically
259
function link(options: LinkOptions): Promise<void>;
260
261
// Run doctor checks programmatically
262
function doctor(options: DoctorOptions): Promise<void>;
263
```
264
265
## Types
266
267
```typescript { .api }
268
interface PostinstallOptions {
269
packageManager: PackageManagerName;
270
configDir: string;
271
yes?: boolean;
272
skipInstall?: boolean;
273
}
274
275
interface UpgradeOptions {
276
packageManager?: PackageManagerName;
277
yes?: boolean;
278
force?: boolean;
279
dryRun?: boolean;
280
skipCheck?: boolean;
281
configDir?: string[];
282
}
283
284
interface SandboxOptions {
285
filterValue?: string;
286
output?: string;
287
branch?: string;
288
init?: boolean;
289
packageManager: PackageManagerName;
290
}
291
292
interface LinkOptions {
293
target: string;
294
local?: boolean;
295
start: boolean;
296
}
297
298
interface DoctorOptions {
299
packageManager?: PackageManagerName;
300
configDir?: string;
301
}
302
303
type PackageManagerName = "npm" | "pnpm" | "yarn1" | "yarn2" | "bun";
304
```