Unity Has a CLI Now — Here's a One-Command Performance Audit (and Safe Auto-Fix) for Your Project

Unity now ships a proper command-line tool — the unity binary — for installing editors, opening projects, and wiring Unity into CI without the Hub. On its own it’s a convenience. But paired with Unity’s Pipeline package, it becomes something more interesting: a bridge that lets you run editor operations from the terminal, against a running editor, with structured output and predictable exit codes.

So here’s a concrete thing worth automating with it: a deterministic performance and asset audit of your project — and a one-command apply of the safe fixes.

One command, against your open editor

With PerfLint installed and Unity’s Pipeline package present, PerfLint registers a few CLI commands. No setup on our side — run unity command with no arguments and the editor lists everything it can do, PerfLint’s commands included. Then:

$ unity command perflint_scan
perflint_scan  true  {"score":39,"grade":"F","findings":337,"critical":0,
                      "warning":125,"info":212,"autoFixable":204,"needsReview":11}

That’s a real run against Unity’s Viking Village sample on Unity 6. No editor path, no -batchmode, no -projectPath, no -executeMethod, and nothing to close — it runs against the editor you already have open and hands back JSON. The scan is deterministic and 100% local: your code and art never leave the machine.

Want a pass/fail gate instead of the full picture?

$ unity command perflint_gate --min_score 60
perflint_gate  true  {"passed":false,"score":39,"grade":"F","violations":"score 39 < 60"}

The command that actually changes something: perflint_fix

perflint_scan and perflint_gate are read-only. The one people want is perflint_fix — and this is where the design choices matter. Preview first:

$ unity command perflint_fix --dry_run
perflint_fix  true  {"status":"dry_run","applied":0,"autoFixable":204,"needsReview":11,
                     "message":"Dry run — nothing changed. 204 auto-fixable, 11 need review."}

Drop the --dry_run and it applies the fixes, re-scans, and reports the delta. On that same Viking Village project, applying the auto-fixable set took it from Grade F to Grade D and lifted the health score from 39 to 59 — and those numbers are the before/after difference of a re-scan, not a tally of what was merely attempted.

Two things it deliberately does not do, and this is the whole point:

• It only auto-applies waste — Read/Write left on a mesh, an uncompressed clip, GPU Instancing enabled under an SRP where it disqualifies the material from the SRP Batcher. Deterministic import/project-settings changes, exactly the set the editor’s “Fix All” applies. Commit before you run it: these are importer writes, which Unity’s undo stack does not record.
• It never auto-applies a trade-off or an AI fix. Disabling Static Batching, merging duplicate assets, lowering a texture cap, an LLM-generated code change — those it reports as needs review (the "needsReview":11 above) and leaves for you. A quality knob is your call, not a script’s.

If that distinction sounds familiar, it’s the same line we’ve written about before: the difference between an AI that rewrites 157 files on one prompt and a tool that tells you which seven are worth changing. The CLI doesn’t make PerfLint guess faster — it makes the deterministic, verified engine scriptable. That’s the half of “AI-driven Unity optimization” that an agent over MCP can’t give you: ground truth and a safe apply, not a plausible sentence.

Fail your CI build on a health regression

The unity command path runs against an open editor — great for your dev loop. CI doesn’t have a running editor, so PerfLint also exposes headless batchmode entry points. This is a gate that fails the build when the project regresses:

Unity -batchmode -projectPath . \
  -executeMethod PerfLint.Ci.PerfLintCli.RunGate \
  -perflintMaxCritical 0 -perflintMinScore 60 \
  -perflintReportHtml perflint-report.html -logFile -

The process exit code is the verdict — 0 pass, 1 gate failed, 2 error — so a CI job blocks a merge automatically. There’s a sibling RunFix that applies the safe fixes headless and prints saved ~X MB, and an ExportReport that writes the shareable HTML report as a build artifact. All of it streams live progress (scan by scanner, apply by batch), so a big-project run never looks frozen.

One honest note on Unity licensing in CI: a hosted runner can’t activate a free Unity Personal license, so the realistic setup is a self-hosted runner with Unity already activated (or a Pro/Plus serial via game-ci). The gate command is identical either way.

What you need, plainly

• The interactive unity command perflint_* path needs Unity 6 plus Unity’s Pipeline package (com.unity.pipeline, currently experimental). Once both are present, PerfLint’s commands show up automatically — there’s nothing to configure.
• The headless batchmode gate/fix/report works on Unity 2021.3 and up — no Pipeline package required.
• Scanning, the gate, and the HTML report are free. Applying fixes is a Pro feature; on a CI runner your license simply counts as one of your seats, like any dev machine.

If you live in the terminal — or you’re wiring Unity into an agent or a build pipeline — unity command perflint_fix is about as close as project optimization gets to a single verb. And because the engine underneath is deterministic, the number it reports is one you can put in a CI check and trust.

---

PerfLint for Unity scans your project locally — performance, assets, and migration — with zero uploads and zero telemetry. Waste is one-click (or one command); trade-offs are yours. Watch the 80-second demo, or read the CLI & CI guide.