---
title: CLI Reference
description:
  You can use the Command-Line Interface (CLI) provided by Bamboo to develop, build, and preview your project from a
  terminal window.
---

Use Bamboo's Command-Line Interface (CLI) to develop, build, and preview your project from a terminal.

## Common flags

These flags are shared between commands and are left out of the per-command tables below. Only `--cwd` is accepted
everywhere; the rest list the commands that take them.

| Flag                  | Description                                                             | Commands                                       | Related                                               |
| --------------------- | ----------------------------------------------------------------------- | ---------------------------------------------- | ----------------------------------------------------- |
| `--cwd <path>`        | Current working directory                                               | all                                            | [`config.cwd`](/docs/references/config#cwd)           |
| `--silent`            | Whether to suppress all output                                          | all except `init-mcp`                          | [`config.logLevel`](/docs/references/config#loglevel) |
| `--config, -c <path>` | Path to Bamboo config file                                              | all except `emit-pkg` and `init-mcp`           | [`config`](/docs/references/config)                   |
| `--logfile <file>`    | Outputs logs to a file                                                  | `init`, `bamboo`, `codegen`, `cssgen`, `debug` | [Debugging](/docs/guides/debugging)                   |
| `--cpu-prof`          | Generate a `bamboo-{command}-{timestamp}.cpuprofile` file for profiling | `bamboo`, `codegen`, `cssgen`, `debug`         | [Debugging](/docs/guides/debugging)                   |

## init

Initialize Bamboo in a project. This process will:

- Create a `bamboo.config.ts` file in your project with the default settings and presets.
- Emit CSS utilities for your project in the specified `output` directory.

```bash
pnpm bamboo init

# Initialize with interactive mode
pnpm bamboo init --interactive

# Initialize with PostCSS config
pnpm bamboo init --postcss
```

| Flag                    | Description                                                                     | Related                                                       |
| ----------------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------------- |
| `--interactive, -i`     | Whether to run the interactive mode                                             | -                                                             |
| `--force, -f`           | Whether to overwrite existing files                                             | -                                                             |
| `--postcss, -p`         | Whether to emit a [postcss](https://postcss.org/) config file                   | -                                                             |
| `--no-gitignore`        | Don't update the `.gitignore` with the output directory                         | [`config.gitignore`](/docs/references/config#gitignore)       |
| `--no-codegen`          | Don't run the codegen process                                                   | -                                                             |
| `--out-extension <ext>` | The extension of the generated js files (default: 'mjs')                        | [`config.outExtension`](/docs/references/config#outextension) |
| `--outdir <dir>`        | The output directory for the generated files                                    | [`config.outdir`](/docs/references/config#outdir)             |
| `--strict-values`       | Require every style value to be a token, so a raw css value is written `[14px]` | [`config.strictValues`](/docs/references/config#strictvalues) |

---

## bamboo

Run the extract process to generate static CSS from your project.

By default it will scan and generate CSS for the entire project depending on your include and exclude options from your
config file.

```bash
pnpm bamboo
# You can also scan a specific file or folder
# using the optional glob argument
pnpm bamboo src/components/Button.tsx
pnpm bamboo "./src/components/**"
```

| Flag                    | Description                                                                     | Related                                                           |
| ----------------------- | ------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
| `--outdir, -o <dir>`    | The output directory for the generated CSS utilities (default: 'styled-system') | [`config.outdir`](/docs/references/config#outdir)                 |
| `--minify, -m`          | Whether to minify the generated CSS                                             | [`config.minify`](/docs/references/config#minify)                 |
| `--watch, -w`           | Whether to watch for changes in the project                                     | [`config.watch`](/docs/references/config#watch)                   |
| `--poll`                | Whether to poll for file changes                                                | [`config.poll`](/docs/references/config#poll)                     |
| `--preflight`           | Whether to emit the preflight or reset CSS                                      | [`config.preflight`](/docs/references/config#preflight)           |
| `--exclude, -e <files>` | Files to exclude from the extract process                                       | [`config`](/docs/references/config)                               |
| `--clean`               | Whether to clean the output directory before emitting                           | [`config.clean`](/docs/references/config#clean)                   |
| `--hash`                | Whether to hash the output classnames                                           | [`config.hash`](/docs/references/config#hash)                     |
| `--polyfill`            | Polyfill CSS @layers at-rules for older browsers                                | [`config.polyfill`](/docs/references/config#polyfill)             |
| `--emitTokensOnly`      | Whether to only emit the `tokens` directory                                     | [`config.emitTokensOnly`](/docs/references/config#emittokensonly) |

---

## codegen

Generate new CSS utilities for your project based on the configuration file.

```bash
pnpm bamboo codegen

# Clean output directory before generating
pnpm bamboo codegen --clean

# Watch for config changes
pnpm bamboo codegen --watch
```

| Flag          | Description                                           | Related                                         |
| ------------- | ----------------------------------------------------- | ----------------------------------------------- |
| `--clean`     | Whether to clean the output directory before emitting | [`config.clean`](/docs/references/config#clean) |
| `--watch, -w` | Whether to watch for changes in the project           | [`config.watch`](/docs/references/config#watch) |
| `--poll, -p`  | Whether to poll for file changes                      | [`config.poll`](/docs/references/config#poll)   |

## cssgen

Generate the CSS from files.

```bash
bamboo cssgen

# Generate CSS for specific type
bamboo cssgen tokens

# Generate CSS for specific glob
bamboo cssgen "src/**/*.css"

# Generate CSS files split into separate files per layer and recipe
bamboo cssgen --splitting
```

When using the `cssgen` command, you can pass a `{type}` argument to generate only a specific type of CSS. The supported
types are: `preflight`, `tokens`, `static`, `global`, `keyframes`.

### CSS Splitting

The `--splitting` flag enables CSS code splitting, which generates separate CSS files for different parts of your design
system instead of a single monolithic CSS file. This is useful for:

- **Selective loading** - Load only the CSS you need for specific pages
- **Easier debugging** - Identify which layer or recipe contributes to the final CSS

When using `--splitting`, Bamboo will generate the following structure:

```
styled-system/
├── styles.css              # @layer declarations + @imports for all layers
└── styles/
    ├── reset.css           # Preflight/reset CSS
    ├── global.css          # Global CSS styles
    ├── tokens.css          # Design token CSS variables
    ├── utilities.css       # Atomic utility classes
    ├── recipes.css         # @imports for all recipe files
    ├── recipes/
    │   ├── button.css      # Individual recipe: button
    │   ├── card.css        # Individual recipe: card
    │   └── ...             # Other recipes as separate files
    └── themes/
        └── dark.css        # Theme-specific tokens (not auto-imported)
        └── light.css       # Theme-specific tokens (not auto-imported)
```

The main `styles.css` file contains the `@layer` declarations and imports all the layer files (but not the themes):

```css
/* styled-system/styles.css */
@layer reset, base, tokens, recipes, utilities;

@import './styles/reset.css';
@import './styles/global.css';
@import './styles/tokens.css';
@import './styles/recipes.css';
@import './styles/utilities.css';
```

Import `styles.css` for everything, or any of the files above on its own — the per-layer, per-recipe and per-theme files
are all importable directly.

| Flag                   | Description                                                                            | Related                                               |
| ---------------------- | -------------------------------------------------------------------------------------- | ----------------------------------------------------- |
| `--outfile, -o [file]` | Output file for extracted css, default to './styled-system/styles.css'                 | -                                                     |
| `--minify, -m`         | Whether to minify the generated CSS                                                    | [`config.minify`](/docs/references/config#minify)     |
| `--clean`              | Whether to clean the output directory before emitting                                  | [`config.clean`](/docs/references/config#clean)       |
| `--watch, -w`          | Whether to watch for changes in the project                                            | [`config.watch`](/docs/references/config#watch)       |
| `--splitting`          | Emit CSS as separate files per layer (reset, global, tokens, utilities) and per recipe | -                                                     |
| `--poll, -p`           | Whether to poll for file changes                                                       | [`config.poll`](/docs/references/config#poll)         |
| `--polyfill`           | Polyfill CSS @layers at-rules for older browsers                                       | [`config.polyfill`](/docs/references/config#polyfill) |

## spec

Generate spec files for your theme (useful for documentation).

```bash
pnpm bamboo spec

# Generate specs in custom directory
pnpm bamboo spec --outdir ./theme-specs
```

| Flag             | Description                     | Related |
| ---------------- | ------------------------------- | ------- |
| `--outdir <dir>` | Output directory for spec files | -       |

> The spec output represents your entire design system, everything available in your Bamboo setup. If you want to
> understand which tokens or recipes your app is actually using, you should use the
> [Bamboo Analyze](/docs/references/cli#analyze), not the spec.

## analyze

Analyze design token and recipe usage.

By default, it will analyze your project based on the `include` and `exclude` config options.

```bash
pnpm bamboo analyze

# analyze a specific file
pnpm bamboo analyze src/components/Button.tsx

# analyze a specific glob
pnpm bamboo analyze "src/components/**"

# analyze only token usage
pnpm bamboo analyze --scope token

# analyze only recipe usage
pnpm bamboo analyze --scope recipe
```

| Flag                   | Description                                  | Related |
| ---------------------- | -------------------------------------------- | ------- |
| `--outfile [filepath]` | Output analyze report in given JSON filepath | -       |
| `--scope <type>`       | Select analysis scope (token or recipe)      | -       |

## debug

Debug design token extraction & CSS generated from files in glob.

More details in [Debugging](/docs/guides/debugging) docs.

```bash
pnpm bamboo debug

# Debug a specific file
pnpm bamboo debug src/components/Button.tsx

# Output to stdout without writing files
pnpm bamboo debug --dry

# Only output resolved config
pnpm bamboo debug --only-config
```

| Flag             | Description                                                           | Related |
| ---------------- | --------------------------------------------------------------------- | ------- |
| `--dry`          | Output debug files in stdout without writing to disk                  | -       |
| `--outdir [dir]` | Output directory for debug files, defaults to `./styled-system/debug` | -       |
| `--only-config`  | Should only output the config file, default to 'false'                | -       |

## ship

Ship extract result from files in glob.

By default it will extract from the entire project depending on your include and exclude options from your config file.

```bash
pnpm bamboo ship
# You can also analyze a specific file or folder
# using the optional glob argument
pnpm bamboo ship src/components/Button.tsx
pnpm bamboo ship "./src/components/**"
```

| Flag                   | Description                                                                                  | Related                                         |
| ---------------------- | -------------------------------------------------------------------------------------------- | ----------------------------------------------- |
| `--outfile <filepath>` | Output path for the JSON build info file, default to './styled-system/bamboo.buildinfo.json' | -                                               |
| `--minify, -m`         | Whether to minify the generated JSON                                                         | -                                               |
| `--watch, -w`          | Whether to watch for changes in the project                                                  | [`config.watch`](/docs/references/config#watch) |
| `--poll, -p`           | Whether to poll for file changes                                                             | [`config.poll`](/docs/references/config#poll)   |

## emit-pkg

Emit package.json with entrypoints, can be used to create a workspace package dedicated to the
[`config.outdir`](/docs/references/config#outdir), in combination with
[`config.importMap`](/docs/references/config#importmap)

```bash
pnpm bamboo emit-pkg

# Specify output directory
pnpm bamboo emit-pkg --outdir styled-system
```

| Flag             | Description                                                        | Related                                           |
| ---------------- | ------------------------------------------------------------------ | ------------------------------------------------- |
| `--outdir <dir>` | The output directory for the generated package.json (default: '.') | [`config.outdir`](/docs/references/config#outdir) |
| `--base <path>`  | The base directory of the package.json entrypoints                 | -                                                 |

## mcp

Removed. The MCP (Model Context Protocol) server ships as its own package so that installing Bamboo does not pull in the
protocol SDK, which brings an HTTP server and a JOSE implementation with it.

```bash
npx -y @bamboocss/mcp
```

Run [`init-mcp`](#init-mcp) to write a client config pointing at it. See the [MCP Server guide](/docs/ai/mcp-server) for
the flags it accepts.

## init-mcp

Initialize MCP configuration for AI clients. This creates the necessary configuration files for AI assistants to connect
to the Bamboo MCP server.

```bash
# Interactive mode - select clients from a list
pnpm bamboo init-mcp

# Configure specific clients
pnpm bamboo init-mcp --client claude,cursor

# Specify working directory
pnpm bamboo init-mcp --cwd ./my-project
```

| Flag               | Description                               | Related |
| ------------------ | ----------------------------------------- | ------- |
| `--client <names>` | AI clients to configure (comma-separated) | -       |

Supported clients: `claude`, `cursor`, `vscode`, `windsurf`, `codex`

See the [MCP Server guide](/docs/ai/mcp-server) for detailed usage and available tools.
