CLI Reference
Purpose and Scope
This page is a developer-facing reference for the public Biome command-line interface, the npm package that exposes it, and the adjacent programmatic entry points that matter when CLI behavior is embedded in tools. A command family is a top-level biome subcommand such as check, format, lint, or migrate. The official CLI reference presents these commands as the primary way to check project health, format files, run lint rules, initialize configuration, operate the daemon, and inspect debugging information.
Sources: packages/@biomejs/biome/package.json, packages/@biomejs/cli-darwin-arm64/package.json
The repository evidence for this page shows that the public npm package is @biomejs/biome, versioned as a distributable package with a bin entry named biome. That package describes Biome as a web toolchain for formatting, linting, and more, and it publishes the launcher script, configuration schema, README, and licenses. The same package declares optional dependencies for operating-system and CPU-specific CLI packages, which is how installing the general package resolves to the appropriate native binary on supported platforms.
Sources: packages/@biomejs/biome/package.json
The platform package evidence is intentionally narrow but illustrative: @biomejs/cli-darwin-arm64 is versioned with the same release number, restricts installation to darwin and arm64, and uses the same license and homepage metadata. Treat these platform packages as implementation artifacts behind the public biome binary, not as separate user-facing command sets. The commands documented below are invoked through biome, regardless of which optional native package supplies the executable on a given machine.
Sources: packages/@biomejs/cli-darwin-arm64/package.json
Relevant Source Files
packages/@biomejs/backend-jsonrpc/src/index.ts- Creates a JSON-RPCWorkspaceclient connected to a daemon process, initializes it with client metadata, and re-exports workspace bindings used by daemon-aware integrations.packages/@biomejs/js-api/src/index.ts- Exposes the JavaScript API surface for selecting WebAssembly distributions and creating aBiomeinstance outside the CLI.packages/@biomejs/plugin-api/index.js- Guards the plugin API package at runtime and directs consumers who want a JavaScript API to@biomejs/js-api.packages/@biomejs/backend-jsonrpc/package.json- Publishes daemon workspace bindings, declares optional native CLI dependencies, and documents the package purpose as JSON-RPC access to the Biome daemon.packages/@biomejs/biome/package.json- Publishes the publicbiomebinary entry point and the general toolchain package metadata.packages/@biomejs/cli-darwin-arm64/package.json- Shows the shape of a platform-specific native CLI package selected through optional dependencies.
Command Families
The top-level command is biome COMMAND .... The official command summary includes version, upgrade, rage, start, stop, check, lint, format, ci, init, lsp-proxy, migrate, search, explain, and clean. It also lists specialized migration commands, including migrate prettier and migrate eslint. Global options include help and version flags at the top level, and the command reference also describes shared flags such as color control, daemon usage, verbosity, and configuration path selection for command execution.
For day-to-day project validation, check is the broad command. It runs the formatter, linter, and import sorting over requested files. ci is the continuous-integration variant with the same conceptual scope: it is meant for automated environments where commands should verify the repository rather than provide an interactive editing workflow. format narrows the operation to formatting, while lint narrows it to analyzer checks. This separation lets teams choose between a single all-in-one gate and more targeted commands for editor tasks, pre-commit hooks, or focused troubleshooting.
Project setup and maintenance commands serve a different lifecycle. init bootstraps a Biome project by creating a configuration file with defaults, so it is the first command to reach for when adopting the toolchain in an existing repository. migrate updates configuration across breaking changes, while migrate prettier and migrate eslint are named migration paths for users moving from established JavaScript ecosystem tools. upgrade updates Biome itself to a newer release, keeping the installed binary aligned with the current command behavior and schema expectations.
Introspection and operational commands are useful when the CLI is being integrated into larger workflows. version prints version information and exits. explain shows documentation for aspects of the CLI, which makes it a local discovery tool when a developer needs command or category context. rage prints debugging information for support and issue reports. search is marked experimental in the official reference and searches Grit patterns across a project, so teams should treat it as a powerful but evolving command family rather than a stable replacement for ordinary lint or formatter checks.
Daemon, LSP, and JSON-RPC Integration
Biome includes daemon-oriented commands in the public CLI: start starts the daemon server process, stop stops it, lsp-proxy acts as a Language Server Protocol server over standard input and standard output, and clean removes daemon logs. These commands matter because editor integrations and long-lived workspace operations often benefit from retaining state instead of launching a fresh process for every request. The CLI reference also mentions --use-server, which tells commands to connect to a running daemon instance.
Sources: packages/@biomejs/backend-jsonrpc/package.json, packages/@biomejs/backend-jsonrpc/src/index.ts
The @biomejs/backend-jsonrpc package is the source-backed bridge for this daemon-oriented model. Its package description says it provides bindings to the JSON-RPC Workspace API of the Biome daemon, and its optional dependencies mirror the native CLI packages used by the main distribution. In code, createWorkspace() resolves a command with getCommand(), returns null when the underlying platform is unsupported, and otherwise delegates to createWorkspaceWithBinary(command) to establish a daemon-backed workspace client.
Sources: packages/@biomejs/backend-jsonrpc/package.json, packages/@biomejs/backend-jsonrpc/src/index.ts
createWorkspaceWithBinary(command) shows the runtime sequence behind that integration. It creates a socket for the provided Biome binary, wraps the socket in a Transport, sends an initialize JSON-RPC request with empty capabilities and client metadata for @biomejs/backend-jsonrpc, and then returns a workspace wrapper over the transport. For CLI users, the important operational lesson is that daemon connectivity is not a separate product; it is an implementation path that supports commands, editor workflows, and API consumers that need a workspace service.
Sources: packages/@biomejs/backend-jsonrpc/src/index.ts
JavaScript API Boundaries
Not every JavaScript package in the repository is a CLI wrapper. @biomejs/js-api exposes a programmatic Biome class that loads one of three WebAssembly distributions: bundler, Node.js, or web. Its Distribution enum names those choices as BUNDLER, NODE, and WEB, and Biome.create({ distribution }) dynamically imports the matching wasm package before constructing the API object. This is the path for applications that need Biome behavior from JavaScript without shelling out to biome.
Sources: packages/@biomejs/js-api/src/index.ts
The JavaScript API also defines the public shape of configuration and diagnostics as unions over the wasm distribution types. That means API consumers can pass configuration and receive diagnostics through a common TypeScript-facing surface, while the selected runtime distribution supplies the actual implementation. This complements the CLI rather than replacing it: the CLI remains the official command surface for terminal workflows, while the JavaScript API is a library boundary for embedded tooling, browser contexts, bundlers, or Node.js applications.
Sources: packages/@biomejs/js-api/src/index.ts
The @biomejs/plugin-api package is deliberately not a general CLI or JavaScript API entry point. Its index.js immediately throws an error saying the package is intended for Biome JS plugins and asks whether the user meant @biomejs/js-api. That guard is useful when debugging dependency confusion: if a tool is trying to format, lint, or analyze files from JavaScript, it should use the documented JavaScript API package, a daemon workspace binding, or the public biome binary rather than importing the plugin API package directly.
Sources: packages/@biomejs/plugin-api/index.js
Compact Command Reference
| Command | Public behavior | Typical use |
|---|---|---|
biome version | Shows Biome version information and exits. | Confirm the installed release in local or CI logs. |
biome upgrade | Upgrades Biome to the latest version. | Move a project to a newer release. |
biome rage | Prints debugging information. | Prepare troubleshooting output for maintainers. |
biome start | Starts the daemon server process. | Prepare a long-lived service for editor or workspace use. |
biome stop | Stops the daemon server process. | Shut down a daemon explicitly. |
biome check | Runs formatter, linter, and import sorting on requested files. | Main local project health command. |
biome lint | Runs checks on a set of files. | Run only lint/analyzer diagnostics. |
biome format | Runs the formatter on a set of files. | Format files without running the linter. |
biome ci | Runs formatter, linter, and import sorting for CI environments. | Enforce repository health in automation. |
biome init | Creates a configuration file with defaults. | Bootstrap Biome in a project. |
biome lsp-proxy | Runs the Language Server Protocol proxy over stdio. | Support editor integrations. |
biome migrate | Updates configuration across breaking changes. | Maintain compatibility after upgrades. |
biome migrate prettier | Migrates Prettier-related configuration. | Adopt Biome formatting from Prettier. |
biome migrate eslint | Migrates ESLint-related configuration. | Adopt Biome linting from ESLint. |
biome search | Experimentally searches Grit patterns across a project. | Structural search workflows. |
biome explain | Shows documentation for CLI concepts. | Learn about command topics locally. |
biome clean | Cleans daemon logs. | Reset daemon log output during troubleshooting. |
Practical Usage Guidance
A practical first workflow is to install @biomejs/biome, run biome init to create configuration, and then use biome check as the default command while the team is still learning how the formatter, linter, and import sorting interact. Once the project has stable conventions, split commands where useful: biome format for formatting-only editor or pre-commit tasks, biome lint for focused diagnostics, and biome ci for automation that should fail when the repository no longer satisfies the configured policy.
When a command behaves differently between local terminals and editors, include daemon state in the investigation. Use biome version to record the executable release, biome rage to gather debugging context, biome stop and biome start to reset the long-lived server path, and biome clean when log cleanup is part of the troubleshooting flow. If a custom integration uses JSON-RPC directly, compare its initialization path with @biomejs/backend-jsonrpc, especially command resolution, socket creation, the initialize request, and workspace wrapping.
Sources: packages/@biomejs/backend-jsonrpc/src/index.ts, packages/@biomejs/backend-jsonrpc/package.json
For embedded JavaScript use cases, choose the boundary intentionally. Use the public biome binary when you want exact CLI behavior and compatibility with the documented command families. Use @biomejs/backend-jsonrpc when you want a workspace client connected to a daemon process. Use @biomejs/js-api when you need a WebAssembly-backed API inside a JavaScript runtime. Avoid @biomejs/plugin-api unless you are actually implementing a Biome JS plugin, because the package is designed to reject ordinary imports with a clear error message.
Sources: packages/@biomejs/js-api/src/index.ts, packages/@biomejs/plugin-api/index.js