BiomeJS CLI Commands: Complete Guide to Format, Lint, Check, and CI

BiomeJS provides a unified single-binary CLI with four primary commands—format, lint, check, and ci—that share global flags for colors, diagnostics, and reporters defined in crates/biome_cli/src/cli_options.rs.

The BiomeJS CLI commands offer a fast, unified interface for formatting, linting, and checking JavaScript/TypeScript codebases. As implemented in the biomejs/biome repository, this single binary exposes a minimal yet powerful command set that leverages the bpaf argument parser and shared core libraries used by the VS Code extension.

How the BiomeJS CLI Parses Arguments

The CLI entry point in crates/biome_cli/src/main.rs uses the bpaf crate to parse command-line arguments. The parser builds a CliOptions struct (lines 8‑66 in crates/biome_cli/src/cli_options.rs) that holds all global configuration before dispatching to sub-commands.

The execution flow follows three steps:

1. Parse arguments with bpaf::Parser::run.
2. Load configuration using CliOptions::as_configuration_path_hint (lines 68‑86).
3. Dispatch to the appropriate sub-command (format, lint, check, or ci).

Each sub-command lives in its own crate—biome_formatter for formatting and biome_analyze for linting—and receives the parsed CliOptions to honor global flags.

Global CLI Flags and Configuration Options

The CliOptions struct in crates/biome_cli/src/cli_options.rs defines several categories of global flags:

• Global switches (lines 11‑21): --colors, --verbose, and --use-server.
• Configuration overrides (lines 23‑31): --config-path for specifying a custom biome.json location.
• Diagnostic limits (lines 33‑40): --max-diagnostics to control output volume.
• Reporter selection (lines 40‑64): --reporter to choose output format (e.g., json, summary).
• Diagnostic filtering (lines 58‑65): --diagnostic-level to filter by severity.

Available BiomeJS CLI Commands

format

The format command runs the Biome formatter on JavaScript, TypeScript, and JSON files. It uses the shared parser and formatter backends defined in crates/biome_formatter/.

# Format all files and write changes

npx @biomejs/biome format --write

lint

The lint command executes the rule engine from crates/biome_analyze/ to identify code issues and automatically apply safe fixes.

# Lint with JSON output and auto-fix safe issues

npx @biomejs/biome lint --write --reporter json

check

The check command runs the full suite—formatting, linting, and import organization—in a single pass. This is the recommended command for development workflows.

# Run complete check suite and apply fixes

npx @biomejs/biome check --write

ci

The ci command runs diagnostics without modifying files, optimized for continuous integration pipelines. It ensures code quality checks fail the build without making changes.

# CI-friendly read-only check

npx @biomejs/biome ci

Reporter System and Diagnostic Output

BiomeJS supports multiple output formats via the --reporter flag. The CliReporterKind enum (lines 40‑64 in cli_options.rs) determines how diagnostics are printed, whether as human-readable text, JSON, or GitHub Actions-compatible annotations.

# Force colored output even in non-TTY environments

npx @biomejs/biome lint --colors=force

# Remove diagnostic limits entirely

npx @biomejs/biome lint --max-diagnostics=none

Configuration Loading and Resolution

The CLI resolves configuration through CliOptions::as_configuration_path_hint (lines 68‑86). This method processes the --config-path flag if provided, otherwise searching for biome.json in the current working directory or parent directories.

Because the CLI shares core libraries with the VS Code extension, behavior remains identical between editor integrations and command-line execution. The formatter uses the same parser, the linter runs the same rule engine, and both use identical caching and diagnostics infrastructure.

Summary

• Single binary architecture: BiomeJS ships as one binary exposing format, lint, check, and ci commands.
• Centralized flags: All global options live in crates/biome_cli/src/cli_options.rs within the CliOptions struct.
• bpaf parsing: The CLI uses the bpaf crate for argument parsing and validation.
• Shared core: Commands rely on biome_formatter and biome_analyze crates, ensuring consistency with editor extensions.
• Flexible reporting: The --reporter flag supports multiple output formats for different integration needs.

Frequently Asked Questions

What is the difference between check and ci commands?

The check command runs formatting, linting, and import organization while optionally writing fixes with --write. The ci command performs the same diagnostics but never modifies files, making it ideal for CI pipelines where you want to verify code quality without side effects.

How do I configure global options like colors and verbosity?

Global options are defined in crates/biome_cli/src/cli_options.rs (lines 11‑21) and include --colors (for forcing color output), --verbose (for detailed logging), and --use-server (for daemon mode). These flags apply to all sub-commands.

Where are the CLI command flags defined in the source code?

All command-line flags are defined in crates/biome_cli/src/cli_options.rs. The CliOptions struct (lines 8‑66) contains global switches, configuration overrides, diagnostic limits, and reporter selection options parsed by the bpaf crate.

Can I use JSON output for diagnostics in CI pipelines?

Yes. Pass --reporter json to any command to output diagnostics as JSON. This is particularly useful when combined with the lint or ci commands for programmatic processing in CI environments, as shown in the biome lint --write --reporter json example.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}