oxlint CLI Reference

oxlint is a high-performance JavaScript and TypeScript linter written in Rust. It’s designed to catch errors and enforce code quality without requiring a configuration file.

Installation

npm install -D oxlint
# or
pnpm add -D oxlint
# or
yarn add -D oxlint

Basic Usage

# Lint current directory
oxlint

# Lint specific files or directories
oxlint src/
oxlint file1.js file2.ts

# Lint and auto-fix issues
oxlint --fix src/

Commands

Default Command (Lint)

The default command runs the linter on specified paths.

oxlint [OPTIONS] [PATH...]

Special Commands

--rules

flag

List all available linting rules with their categories and descriptions.

oxlint --rules

--init

flag

Initialize a new .oxlintrc.json configuration file with default values.

oxlint --init

--lsp

flag

Start the Language Server Protocol (LSP) server for editor integration.

oxlint --lsp

Configuration Options

Basic Configuration

-c, --config

path

default:".oxlintrc.json"

Path to the oxlint configuration file.Supported formats:

.json and .jsonc files (all runtimes)
JavaScript/TypeScript config files (experimental, requires Node.js)
Comments are supported in configuration files
Compatible with ESLint v8’s format

If not provided, oxlint searches for .oxlintrc.json, .oxlintrc.jsonc, or oxlint.config.ts in the current directory.

oxlint --config custom-config.json src/

--tsconfig

path

default:"./tsconfig.json"

Path to TypeScript tsconfig.json for reading path aliases and project references (used by the import plugin).If not provided, oxlint looks for tsconfig.json in the current working directory.

oxlint --tsconfig ./configs/tsconfig.json src/

--disable-nested-config

flag

Disable automatic loading of nested configuration files.By default, oxlint loads configuration files found in subdirectories. This flag disables that behavior.

oxlint --disable-nested-config src/

Rule Configuration

oxlint uses a category-based rule system. Rules can be enabled or disabled using command-line flags.

Rule Categories

correctness - Code that is outright wrong or useless (enabled by default)
suspicious - Code that is most likely wrong or useless
pedantic - Strict lints with occasional false positives
perf - Code that could be more performant
style - Code that should be written more idiomatically
restriction - Lints preventing use of language/library features
nursery - New lints under development
all - All categories except nursery (does not auto-enable plugins)

-A, --allow

string

Allow (suppress) a rule or category.Can be specified multiple times. Rules are processed left-to-right.

# Allow all rules in the pedantic category
oxlint -A pedantic src/

# Allow specific rule
oxlint -A no-debugger src/

# Allow all, then deny specific rules
oxlint -A all -D no-debugger src/

-W, --warn

string

Warn on a rule or category (emit a warning instead of error).

oxlint -W suspicious src/

-D, --deny

string

Deny (enable) a rule or category (emit an error).

# Enable suspicious and pedantic categories
oxlint -D suspicious -D pedantic src/

# Enable all rules except specific ones
oxlint -D all -A no-debugger src/

Fix Options

--fix

flag

Automatically fix as many issues as possible.Only safe fixes are applied. Unfixed issues are still reported.

oxlint --fix src/

--fix-suggestions

flag

Apply auto-fixable suggestions.Warning: May change program behavior.

oxlint --fix-suggestions src/

--fix-dangerously

flag

Apply dangerous fixes and suggestions.Warning: May significantly change program behavior. Review changes carefully.

oxlint --fix-dangerously src/

Plugin Options

Plugins extend oxlint with additional rules. Some plugins are enabled by default.

Enabled by Default

oxc - Oxc-specific rules
typescript - TypeScript rules
unicorn - Unicorn plugin rules

--disable-oxc-plugin

flag

Disable the oxc plugin (enabled by default).

oxlint --disable-oxc-plugin src/

--disable-typescript-plugin

flag

Disable TypeScript plugin (enabled by default).

oxlint --disable-typescript-plugin src/

--disable-unicorn-plugin

flag

Disable unicorn plugin (enabled by default).

oxlint --disable-unicorn-plugin src/

Optional Plugins

--import-plugin

flag

Enable import plugin to detect ESM problems.Use with --tsconfig if your project uses a non-standard tsconfig name.

oxlint --import-plugin --tsconfig ./tsconfig.json src/

--react-plugin

flag

Enable React plugin for React-specific rules.

oxlint --react-plugin src/

Enable JSX accessibility plugin to detect accessibility issues.

oxlint --jsx-a11y-plugin src/

--nextjs-plugin

flag

Enable Next.js plugin for Next.js-specific rules.

oxlint --nextjs-plugin src/

--react-perf-plugin

flag

Enable React performance plugin to detect rendering performance issues.

oxlint --react-perf-plugin src/

--jsdoc-plugin

flag

Enable JSDoc plugin to detect JSDoc problems.

oxlint --jsdoc-plugin src/

--jest-plugin

flag

Enable Jest plugin for Jest test rules.

oxlint --jest-plugin src/

--vitest-plugin

flag

Enable Vitest plugin for Vitest test rules.

oxlint --vitest-plugin src/

--promise-plugin

flag

Enable promise plugin to detect promise usage issues.

oxlint --promise-plugin src/

--node-plugin

flag

Enable Node.js plugin for Node.js-specific rules.

oxlint --node-plugin src/

--vue-plugin

flag

Enable Vue plugin for Vue.js-specific rules.

oxlint --vue-plugin src/

Type Checking

--type-aware

flag

Enable rules that require type information.Requires a valid TypeScript configuration.

oxlint --type-aware src/

--type-check

flag

Enable experimental type checking (includes TypeScript compiler diagnostics).

oxlint --type-check src/

Warning Options

--quiet

flag

Disable reporting warnings, only report errors.

oxlint --quiet src/

--deny-warnings

flag

Ensure warnings produce a non-zero exit code.Useful in CI/CD pipelines to fail builds on warnings.

oxlint --deny-warnings src/

--max-warnings

number

Specify maximum number of warnings allowed.Exit with error status if warning count exceeds this threshold.

oxlint --max-warnings 10 src/

Output Options

-f, --format

string

default:"default"

Specify the output format.Available formats:

default - Human-readable format (auto-detects GitHub Actions)
stylish - Stylized output format
json - JSON format for programmatic parsing
unix - Unix-style output
checkstyle - Checkstyle XML format
github - GitHub Actions format
gitlab - GitLab format
junit - JUnit XML format

When running in GitHub Actions, automatically uses github format.

oxlint --format json src/ > results.json

--silent

flag

Do not display any diagnostics.

oxlint --silent src/

Ignore Options

--ignore-path

path

default:".eslintignore"

Specify the file to use as your ignore file.

oxlint --ignore-path .gitignore src/

--ignore-pattern

string

Specify patterns of files to ignore (in addition to those in ignore file).Can be specified multiple times. Uses same syntax as .eslintignore and .gitignore. Quote patterns to avoid shell interpretation.

oxlint --ignore-pattern '**/*.test.js' --ignore-pattern '**/fixtures/*' src/

--no-ignore

flag

Disable excluding files from .eslintignore files, --ignore-path, and --ignore-pattern flags.

oxlint --no-ignore src/

Inline Configuration Comments

--report-unused-disable-directives

flag

Report directive comments like // oxlint-disable-line when no errors would have been reported on that line.Helps keep codebase clean of unnecessary disable directives.

oxlint --report-unused-disable-directives src/

--report-unused-disable-directives-severity

string

Same as --report-unused-disable-directives, but specify severity level.Options: allow, warn, deny, errorOnly one of these options can be used at a time.

oxlint --report-unused-disable-directives-severity=warn src/

Performance Options

--threads

number

Number of threads to use for linting.Set to 1 to use only 1 CPU core. By default, uses all available CPU cores.

oxlint --threads 4 src/

Miscellaneous

--print-config

flag

Output the configuration that would be used for linting.No linting is performed when this flag is present.

oxlint --print-config

Exit Codes

oxlint uses the following exit codes:

Exit Code	Meaning
0	Success - no linting errors found
1	Failure - linting errors found, invalid configuration, or other errors

Exit codes in detail:

0 (Success)
- No errors found
- --rules or --print-config executed successfully
- --init executed successfully
- No files found (currently returns success)
1 (Failure)
- Linting errors found
- Configuration file invalid
- TypeScript configuration invalid
- --max-warnings threshold exceeded
- --deny-warnings used and warnings found
- Invalid command-line options
- JavaScript plugin workspace setup failed

Configuration File

oxlint supports configuration files compatible with ESLint v8 format.

Example `.oxlintrc.json`

{
  "rules": {
    "no-debugger": "error",
    "no-console": "warn"
  },
  "env": {
    "browser": true,
    "es2021": true
  },
  "categories": {
    "correctness": "error",
    "suspicious": "warn"
  },
  "plugins": ["react", "jsx-a11y"]
}

Integration Examples

CI/CD Integration

GitHub Actions

name: Lint

on: [push, pull_request]

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
      - run: npm install
      - run: npx oxlint --deny-warnings src/

GitLab CI

lint:
  script:
    - npm install
    - npx oxlint --format gitlab --deny-warnings src/

Pre-commit Hook

Using Husky

// package.json
{
  "scripts": {
    "prepare": "husky install"
  }
}

# .husky/pre-commit
npx oxlint --fix

Using lint-staged

// package.json
{
  "lint-staged": {
    "*.{js,jsx,ts,tsx}": "oxlint --fix"
  }
}

NPM Scripts

{
  "scripts": {
    "lint": "oxlint src/",
    "lint:fix": "oxlint --fix src/",
    "lint:ci": "oxlint --deny-warnings --format json src/ > lint-results.json"
  }
}

Performance Tips

Use Multiple Threads: oxlint automatically uses all available CPU cores. For large projects, this provides significant speedup.
Disable Unused Plugins: Only enable plugins you need. Disabling unused default plugins can improve performance:
```
oxlint --disable-unicorn-plugin src/
```
Ignore Patterns: Use --ignore-pattern to skip files that don’t need linting:
```
oxlint --ignore-pattern '**/*.test.js' src/
```

Targeted Linting: In CI/CD, lint only changed files:

git diff --name-only --diff-filter=ACMR main... | grep '\.\(js\|ts\|jsx\|tsx\)$' | xargs oxlint

Type-Aware Rules: Only enable --type-aware when necessary, as it requires TypeScript type checking which adds overhead.

Common Use Cases

Lint with Auto-fix

oxlint --fix src/

Strict Linting for CI

oxlint --deny-warnings --max-warnings 0 -D all -A nursery src/

React Project

oxlint --react-plugin --jsx-a11y-plugin src/

TypeScript Project with Type Checking

oxlint --type-aware --tsconfig ./tsconfig.json src/

Generate JSON Report

oxlint --format json src/ > lint-report.json

Progressive Adoption

# Start with errors only, allow all warnings
oxlint -A all -D correctness src/

# Gradually enable more categories
oxlint -A all -D correctness -D suspicious src/

Inline Directives

Disable rules using comments in your code:

// Disable for entire file
/* oxlint-disable */

// Disable specific rule for file
/* oxlint-disable no-debugger */

// Disable for next line
// oxlint-disable-next-line
console.log('debug');

// Disable specific rule for next line
// oxlint-disable-next-line no-console
console.log('debug');

// Disable for current line
console.log('debug'); // oxlint-disable-line

// Re-enable rules
/* oxlint-enable */

Node.js APIs

Rust APIs

CLI Reference

​oxlint CLI Reference

​Installation

​Basic Usage

​Commands

​Default Command (Lint)

​Special Commands

​Configuration Options

​Basic Configuration

​Rule Configuration

​Rule Categories

​Fix Options

​Plugin Options

​Enabled by Default

​Optional Plugins

​Type Checking

​Warning Options

​Output Options

​Ignore Options

​Inline Configuration Comments

​Performance Options

​Miscellaneous

​Exit Codes

​Configuration File

​Example .oxlintrc.json

​Integration Examples

​CI/CD Integration

​GitHub Actions

​GitLab CI

​Pre-commit Hook

​Using Husky

​Using lint-staged

​NPM Scripts

​Performance Tips

​Common Use Cases

​Lint with Auto-fix

​Strict Linting for CI

​React Project

​TypeScript Project with Type Checking

​Generate JSON Report

​Progressive Adoption

​Inline Directives

​Troubleshooting

​No Files Found

​Performance Issues

​Configuration Not Loading

​See Also

Build docs developers (and LLMs) love

oxlint CLI Reference

Installation

Basic Usage

Commands

Default Command (Lint)

Special Commands

Configuration Options

Basic Configuration

Rule Configuration

Rule Categories

Fix Options

Plugin Options

Enabled by Default

Optional Plugins

Type Checking

Warning Options

Output Options

Ignore Options

Inline Configuration Comments

Performance Options

Miscellaneous

Exit Codes

Configuration File

Example `.oxlintrc.json`

Integration Examples

CI/CD Integration

GitHub Actions

GitLab CI

Pre-commit Hook

Using Husky

Using lint-staged

NPM Scripts

Performance Tips

Common Use Cases

Lint with Auto-fix

Strict Linting for CI

React Project

TypeScript Project with Type Checking

Generate JSON Report

Progressive Adoption

Inline Directives

Troubleshooting

No Files Found

Performance Issues

Configuration Not Loading

See Also