Setup

Installation

It is recommended that you install Stackbit locally on your machine.

npm install -g @stackbit/cli

This adds the stackbit command to your path. See below for usage instructions.

Usage

To see a list of available commands use the --help flag:

stackbit --help

Usage:
  stackbit [command]

Commands:
  stackbit validate           validates stackbit configuration and any content
                              against the schema defined in configuration
  stackbit init               Generates stackbit.yaml by introspecting website
                              project files
  stackbit analyze-repo       Analyze GitHub repository for SSG and CMS, use to
                              debug repositories imported via
                              stackbit.com/import
  stackbit telemetry-enable   Enable telemetry
  stackbit telemetry-disable  Disable telemetry
  stackbit dev                Stackbit Local development server

Options:
  --help     Show help                                                 [boolean]
  --version  Show version number                                       [boolean]

See below for a list of commands.

Direct Usage with npx

Rather that installing globally, you can also use the CLI directly with npx:

npx @stackbit/cli [command]

⚠️ Because the CLI package has a large number of dependencies, this is not recommended, as it will take much longer to run a command.

Commands

dev

Boot Stackbit dev, our local development server, used for developing projects locally before importing into production with Stackbit. Learn more about local development.

cd my-stackbit-site
stackbit dev

init [experimental]

⚠️ This command has not been updated for full support of Stackbit v2. Use is experimental and may be removed in a future version.

You can also create a new project using create-stackbit-app, or follow the integration guide to add Stackbit to your site.

The init command introspects your project files and generates the initial stackbit.yaml for you. To generate a new stackbit.yaml file, run the init command inside your project's root folder:

cd my-website
stackbit init

Stackbit CLI will generate the initial stackbit.yaml according to your project files. If your project doesn't use any CMS, the init command will also generate the content model. The content model generation relies on your project's content files (e.g., .md, .json, .yaml).

Note that the generated stackbit.yaml is the "best guess", so it might not have the best content model for your site. For example, fields that could store markdown content might be marked as strings. After generating the stackbit.yaml file, we recommend reviewing it and adjusting it if needed. We also recommend running the validate command to check if there are content files without matched models.

validate [experimental]

⚠️ This command has not been updated for full support of Stackbit v2. Use is experimental and may be removed in a future version.

The validate command is used to validate Stackbit configuration. It runs the following validation steps:

  1. It loads the stackbit.yaml from the current working directory and validates its structure according to the specification.
  2. It loads your site's content files from folders defined by the pagesDir and the dataDir properties.
  3. It matches the loaded content files to the models defined in stackbit.yaml using the "model matching properties" such as file, folder, match and exclude.
  4. It validates the structure of your content files against the models defined in the stackbit.yaml.

If the validator finds any errors during these validation steps, it will print them to your console providing contextual information allowing you to fix them.

analyze-repo [experimental]

⚠️ This command has not been updated for full support of Stackbit v2. Use is experimental and may be removed in a future version.

telemetry-enable & telemetry-disable

Stackbit contains a telemetry feature that collects anonymous information on the usage of Stackbit CLI commands. We do this to improve the reliability of Stackbit CLI and help drive new features and improvements. Learn more about data collected via telemetry.

If you’d like to opt-out of sending usage information, you can do so by running the following command:

# opt out of sharing usage information
stackbit telemetry-disable

# allow collecting your usage information
stackbit telemetry-enable