---
title: Usage
description: This section covers how to use Ultracite on a day-to-day basis — covering the command-line interface, editor integration details, and typical workflows.
---

## IDE Integration

Ultracite works best when integrated into your editor, so you get immediate feedback as you write code. It is designed to run automatically on save.

To test it out, open a project in your IDE. As you edit files, you should see formatting take effect on save. Try introducing a small code style mistake (like an extra semicolon or a wrongly indented line) and hit Save — Ultracite will instantly reformat the file.

If you introduce a lint issue (like an unused variable), you'll see a squiggly underline or a warning in the Problems panel. On save, Ultracite will attempt to fix it if it's auto-fixable (for example, removing an unused import) or otherwise leave a warning for you to address.

### Instant formatting

Every time you save a file, your chosen linter formats the code. You don't need to run a separate formatter or worry about style — it's taken care of.

Thanks to the `codeActionsOnSave` settings, VS Code will also apply "fix all" actions on save. This means any lint rule with an auto-fix (like converting `!=` to `!==`, adding missing parentheses, fixing import order, etc.) will be applied automatically.

We also enable `formatOnPaste` — so if you paste code from elsewhere, it will immediately be formatted to match your style.

The key advantage is instant feedback. You write code, and Ultracite continuously keeps it clean. Over time, you'll spend little to no time fixing lint errors — Ultracite either fixes them for you or points them out early.

### Problems panel integration

Any issues that require your attention will show up in the Problems panel. For example, if Ultracite finds an error it can't fix (like a deprecated API or an unhandled Promise rejection), it will list it as an error or warning. Click it to jump to the location in code.

### Quick fixes

In many cases, the VS Code extension for your linter provides quick fix suggestions. If you see a yellow lightbulb or a suggestion popup, you can apply fixes manually as well.

## CLI Usage

Ultracite comes with a CLI that wraps your chosen linter. The commands work the same regardless of which toolchain you're using.

Any unknown flags are passed through to the underlying linter, so you can use any flag your linter supports (e.g. `--max-warnings` for ESLint, `--since` for Biome). If you need to lint a file path that starts with `-`, pass it after `--` so Ultracite treats it as a file instead of a linter flag.

### Checking Code

The `check` command runs the linter without modifying files:

```bash title="Terminal"
npx ultracite check
```

### Fixing Code

The `fix` command runs the linter and auto-fixes issues:

```bash title="Terminal"
npx ultracite fix
```

You can also apply unsafe fixes (fixes that may change code behavior):

```bash title="Terminal"
npx ultracite fix --unsafe
```

Some Biome fixes are intentionally marked unsafe because they can change runtime behavior. For example, Ultracite already enables Biome's `noSubstr` rule, but rewriting `substring()` or `substr()` to `slice()` only happens when you run `ultracite fix --unsafe`.

### AI-Powered Fixing

The `--claude` and `--codex` flags hand any issues that survive the autofix pass to a local agent CLI, which repairs them autonomously — file by file, with a live per-issue status line that flips to ✓ once the fix is verified:

```bash title="Terminal"
npx ultracite fix --claude
npx ultracite fix --codex
```

The flow: Ultracite runs its normal autofix pass, collects the remaining (unfixable) diagnostics, and then invokes the agent once per affected file with the full, untruncated diagnostics — including rule help text and documentation URLs. After each agent run, Ultracite re-lints the file and only marks an issue fixed if the diagnostic actually cleared. If any diagnostics survive, the agent gets up to two more attempts on that file, each with the fresh post-edit diagnostics and explicit feedback that the previous approach failed — so a superficial edit that dodges the symptom rather than the rule gets caught and retried instead of reported as fixed. The command exits non-zero if any issues remain, matching the plain `fix` contract.

Requirements and behavior:

- `--claude` requires the [Claude Code CLI](https://claude.com/claude-code) (`npm install -g @anthropic-ai/claude-code`); `--codex` requires the [Codex CLI](https://github.com/openai/codex) (`npm install -g @openai/codex`). Both must be authenticated.
- Agents run non-interactively with scoped permissions: Claude Code uses `--permission-mode acceptEdits` limited to read/edit tools (no shell access), and Codex runs in its workspace-write sandbox via `codex exec --sandbox workspace-write`.
- Each agent attempt gets a 5-minute budget, and the re-lint decides the outcome either way — even a failed or timed-out run gets credit for diagnostics it managed to clear. Whatever remains unfixed after the attempts is marked ✗ and the run continues with the next file.
- Other flags combine as usual, e.g. `npx ultracite fix --claude --type-aware --unsafe`.

### Type-Aware Linting

Type-aware linting enables deeper analysis rules that leverage TypeScript's type system and project structure. The `--type-aware` flag is passed during `ultracite init` and configures your project accordingly.

#### Biome

For Biome, `--type-aware` adds the `ultracite/biome/type-aware` preset to your Biome config's `extends` array. This enables project/scanner rules like `noPrivateImports`, `noUndeclaredDependencies`, `noUnresolvedImports`, `noImportCycles`, and `noDeprecatedImports`.

```bash title="Terminal"
npx ultracite init --linter biome --type-aware
```

Since the rules are baked into your Biome config, they work in both the CLI and your IDE automatically — no runtime flags needed.

#### Oxlint

For Oxlint, `--type-aware` installs the required `oxlint-tsgolint` dependency. You then pass the flag at runtime when checking or fixing:

```bash title="Terminal"
npx ultracite check --type-aware
npx ultracite fix --type-aware
```

This enables rules like `no-floating-promises`, `no-misused-promises`, and `await-thenable` that catch bugs by analyzing types.

You can also enable TypeScript compiler diagnostics (experimental):

```bash title="Terminal"
npx ultracite check --type-check
npx ultracite fix --type-check
```

Both flags can be combined:

```bash title="Terminal"
npx ultracite fix --type-aware --type-check
```

:::note
The `--type-aware` and `--type-check` runtime flags only apply to Oxlint. For Biome, type-aware rules are configured at init time and require no runtime flags.
:::

### Validating Setup

The `doctor` command checks your setup for issues and provides recommendations. This is useful to run after installing Ultracite to ensure everything is configured correctly:

```bash title="Terminal"
npx ultracite doctor
```

Alongside the config checks, `doctor` compares the linter and formatter installed in your project against the versions this Ultracite release was verified with — Biome, ESLint, Prettier and Stylelint, or Oxlint and Oxfmt. A tool that is too old fails the check, because the presets reference rules it doesn't know about yet (the `Found an unknown key` crash). A tool that is newer than the supported range only warns.

### Upgrading

Ultracite's presets are pinned to specific linter releases, so bumping `ultracite` on its own can leave the linter behind. The `upgrade` command moves both together:

```bash title="Terminal"
npx ultracite upgrade
```

It:

1. Installs the latest `ultracite` release and prints a link to the release notes between your previous and new versions.
2. Hands off to the freshly installed CLI, so the rest of the upgrade uses the versions that release was verified with rather than the ones baked into the older copy.
3. Reinstalls your toolchain at those versions — Biome; ESLint, Prettier, Stylelint and every plugin the preset imports; or Oxlint and Oxfmt. Optional extras you've already opted into (framework plugins, Oxlint JS plugins, `oxlint-tsgolint`) are bumped too; ones you never installed are left alone.
4. Runs the same diagnostics as `doctor` and exits non-zero if anything still fails.

Your configuration files are never rewritten. If the release notes call out preset changes, re-run `npx ultracite init` to regenerate them.

Pass `--pm <pm>` to choose the package manager when it can't be detected from a lockfile.