CLI Reference

The @vtex/fsp-cli is the glue that ties all modules together, both in local development and when building the modules.

Commands

Init

The init command sets up the store monorepo for development.

Arguments

N/A

Flags

Flag	Semantics
--from-discovery	Initializes the store monorepo from an existing Discovery repo
--template <id>	Initializes the monorepo from a store template; cannot be combined with --from-discovery

init writes only @vtex/fsp-cli into the root manifest — each module declares the CLI that builds it — and adds the setting that keeps those CLIs’ dependencies apart for the package manager it detects. See the monorepo reference for both. The package manager the project already uses is carried over rather than replaced.

With --template b2b.store, init asks for the account name and a directory (defaulting to the account name), downloads the template, replaces {ACCOUNT_NAME} with the account everywhere it appears and copies the whole repository into the directory. The template’s root files are kept as published, so the pins and workarounds its team validated stay in place — including its packageManager: b2b.store is a Yarn Classic monorepo (nohoist, resolutions and its postinstall only exist there), and init does not convert it. The only changes init makes are the module contract repair’s: each module declares its own CLI (moved out of the root devDependencies when the root had it), and the workspace and isolation settings cover every module. Nothing is installed: the command ends by printing the cd, install and fsp dev steps to run next. --template starter.store is rejected, because that template is a single module and belongs to fsp create.

Create

This command creates a new module customization. If no argument is passed to the command, a wizard will guide the user through all the options, starting with the store type: B2C Discovery (the default) continues with the module and path prompts below; B2B Buyer Portal switches to the b2b.store template flow. Passing module positionally skips that question, so existing scripts see no new prompt.

Arguments

Argument	Semantic	Required
account	the account that will be customized	false
module	the module that will be customized	false
path	the path where the module customization code will live	false

After scaffolding, create adds the module’s CLI to the manifest it just wrote, puts the module in the workspace globs, and updates the isolation setting if that manager needs one — so the new module builds without further setup. See fsp doctor.

Flags

Flag	Semantics
--template <id>	Creates from a store template. starter.store (the default) behaves exactly as omitting the flag.

With --template b2b.store, the module directories come from the template instead of a module CLI’s scaffold. The module argument picks one of the modules the template ships; without it, the wizard offers all of them (checked by default) and asks a path for each. The default path is the template’s own layout (packages/discovery, packages/checkout) unless that directory is already taken, in which case it becomes ./packages/<account>/<module>. Each copied module’s package.json is renamed to <account>-<module> (acme-discovery, acme-checkout), since workspace names must be unique in the monorepo and the template’s are per store; that is the only edit besides the placeholder. faststore.json, the ports and the repair step are handled as for any other module, and the package manager’s install runs at the end so the copied modules’ dependencies are in place. On Yarn Classic the template’s workspaces.nohoist globs are merged into the root manifest; the template root’s resolutions, overrides and postinstall are not applied, since the root is shared with every other store in the monorepo — the warning prints them, with the postinstall already rewritten to the paths you chose, so they can be pasted into the root if it needs them. A script that acts on a module you did not add is named in the warning but not shown, since at that path the host may have another store’s module. create --template refuses to run where there is no root package.json; the module starter keeps running wherever faststore.json loads. If any targeted module already exists for the account, or two modules would land in the same directory, nothing is written.

Store templates

Id	Label	Kind	Source
starter.store	B2C Discovery	module starter	scaffolded by @faststore/cli create
b2b.store	B2B Buyer Portal	monorepo	vtex-sites/b2b.store, default branch

The ids and labels are the ones FastStore WebOps shows when creating a repository, so a store created from either tool looks the same. A monorepo template is a Git repository whose root faststore.json declares exactly one store, keyed by the literal {ACCOUNT_NAME}, whose modules point to directories inside the repository, each with its own package.json; it ships regular files only (no symbolic links, which not every platform can materialize). fsp downloads it as a tarball of its default branch (no git needed), checks that contract, and only then writes into the project. A template that cannot be downloaded — offline, the repository made private, or an archive entry the extraction had to drop — fails the command before anything is written. Because the source is a branch, two runs on different days may fetch different revisions; fsp does not record which one it used.

Dev

This command starts the development environment for a given account The account must be a key on the stores object inside the faststore.json file.

All modules listed inside the stores.{account} key will be started on their assigned ports and a proxy server will be started on port 3000 by default to provide a seamless experience when customizing multiple modules.

Arguments

Argument	Semantic	Required
account	the account for which the development servers will be started	true

Flags

Argument	Semantic	Required
--proxy-port	a custom port for the proxy server to be started on	false

Build

The build command is used to build the production-ready version of each module of an account. If no modules are specified as an argument, all modules will be built. The account and modules specified must match what’s available on faststore.json.

Arguments

Argument	Semantic	Required
account	the account for which the modules will be built	true
moduleList	a comma separated list of modules to build.	false

Flags

N/A

Doctor

Checks that the monorepo keeps each module’s dependencies to itself, and repairs it with --fix. dev and build run the same checks but only report; this is the command that changes anything. See fsp doctor for what it looks at.

Arguments

Argument	Semantic	Required
account	the account to check. Defaults to every account configured.	false

Flags

Flag	Semantics
--fix	Apply the repairs instead of only reporting them

Serve

Run the output of the build command locally.

Arguments

Argument	Semantic	Required
account	the account for which we are running the build outputs	true

Flags

N/A

Lifecycle hooks

A module CLI can ask fsp to run one of its own commands around dev, build or serve. It declares that in its package.json, mapping a lifecycle point to a command it ships:

{
  "fsp": {
    "hooks": {
      "preBuild": "analyze",
      "postBuild": "report"
    }
  }
}

The available points are preDev, postDev, preBuild, postBuild, preServe and postServe. A hook receives the same arguments as the command it wraps, and runs in its own process like any other module command — so it resolves its own dependencies, and a non-zero exit fails the fsp command that triggered it.

Modules that declare no hooks are simply skipped; nothing is loaded to find that out.

Note that postDev runs once the dev servers have been started rather than once they are accepting connections. fsp starts them and brings up its proxy without waiting, so the proxy is there while they are still booting.