# Fractal CLI Tool
The Fractal CLI tool is an optional, globally-installed NPM package that provides some useful commands for working with Fractal projects.
# Installation & setup
The Fractal CLI tool can be installed globally via NPM:
npm i -g @frctl/fractal
To use the CLI tool with your Fractal project, you must first make sure you have a project settings file (typically called
fractal.js) in the root of your project directory. This file should export a configured Fractal instance. For example:
// fractal.js var fractal = require('@frctl/fractal').create(); fractal.set('project.title', 'FooCorp Component Library'); fractal.components.set('path', __dirname + '/src/components'); module.exports = fractal; // export the configured Fractal instance for use by the CLI tool.
Note for Windows users
On Windows, a conflicting command-line application prevents you from running Fractal commands from the project's root directory (where
fractal.js is). To use the CLI, you can run commands from a subdirectory or change the name of Fractal's configuration file. (See the github issue for more details.)
# Running commands
Commands are run from the command line, and typically take the format:
fractal <command-name> [args] [opts]
For example, to start the web UI dev server using the BrowserSync option, you can use the command:
fractal start --sync
When running commands in this format, the command will run and then immediately exit (unless it is watching or running a server in the background).
Fractal also provides a more immersive interactive mode that makes running multiple commands easier and faster.
# Command types
The Fractal CLI supports two different types of command - global and project-level commands.
# Global commands
Global commands can be run from anywhere outside of a project folder. An example of a global command is the
fractal new <project-name> command which helps you quickly create a new Fractal project file structure.
# Project commands
Project-level commands must be run from within the root directory of your project, and require the presence of a project settings file in the root of the project directory.
An example of a project-level command would be the
fractal start command that starts up the project settings file for the web UI.