Overview
The Format CLI creates projects and documents, runs Studio, compiles renderers, and keeps every Format package on one release.
The CLI is the front door to Format. It scaffolds projects, documents, runs Studio, compiles your renderers, and manages every Format package to a single pinned version.
Installation
The CLI should generally be installed in your dev dependencies.
npm install "@format.dev/cli" --save-devpnpm add "@format.dev/cli" --save-devyarn add "@format.dev/cli" --devbun add "@format.dev/cli" --devOnce you have the CLI installed, you can call it by using npx (or your package manager's equivalent). For example.
npx format ...pnpm dlx format ...yarn dlx format ...bun x format ...# Create a new document in your Studio project
npx format new document
# Run the Studio dev server
npx format dev
# Compile your documents to a renderer
npx format compileIn some cases, you will need to add additional Format packages. You should use format add for this.
# Installs the Format React SDK
npx format add "@format.dev/react"Versioning
The entire Format platform runs off a single version number. This keeps versioning predictable and simple to manage. You set your exact version in your format.config.json and all Format packages will install at exactly that pinned version. We don't support symbols you might be used to using, such as ~ or ^. You must specify an exact version.
As long as you add Format packages using the CLI's format add command, your packages will automatically be installed as the right version.
To change your Format version, you can use the format update command.
# Updates all Format packages to the latest stable version
format update latest
# Updates/downgrades to Format version 1.0.2
format update 1.0.2
# Applies the version in your configuration file, updating any packages that don't match it
format updateUse format version to check the current version, or see your configuration file.
Quick guide
| Command | What it does |
|---|---|
npx format new project | Creates a new Format project (same as npm create format@latest) |
npx format init | Sets up Format in an existing project |
npx format new document | Creates a new document |
npx format dev | Runs Format Studio |
npx format compile | Compiles your documents into a renderer |
npx format add | Installs Format packages at the pinned release |
npx format update | Moves to a new Format version |
npx format version | Shows the current version and alerts for package misalignment |