Using Project Auditor Project Auditor carries out a static analysis scan of the Unity Project and reports a list of CSV issues that may be fixed. Trigger, poll, read.
Prerequisites
To use Project Auditor you'll need the Unity CLI installed - see the unity-cli skill for more details. Once you have that, the audit and audit_status commands run Project Auditor checks.
audit_status terminal status are completed (with csvPath + issueCount), failed, unavailable, and
interrupted (a domain reload killed the scan — just re-run audit). Polling is responsive while a
scan compiles assemblies and is busy on the main thread. You can only run one scan at a time: a second audit
returns busy. There is no cancel — stop polling to abandon a scan.
The output CSV has columns: Category, Severity, Areas, Description, RelativePath, Line, DescriptorId, Recommendation
(these are diagnostics only, so every row is something to fix; Recommendation says how to do it).
Requires Project Auditor plus its rules.
unavailablemeans the Editor has no Project Auditor, or it has no analysis rules — in a built-in-module Editor the rules live in the separatecom.unity.project-auditor-rulespackage (unity command package_add --identifier com.unity.project-auditor-rules --confirm true). Read themessagefield; the command never reports an emptycompletedscan that would look like a clean project.
Gotchas
set_autotickfirst. Without it, recompile and tests can hang while the editor is unfocused. The package's watchdog relies on the tick loop staying alive.- Hot reload needs the game running.
reload_file_override/reload_fileapply to a live game — enter Editor Play Mode (unity command editor_play) first, or run a dev Player. - Player-only commands need a dev Player.
log,set_timescale,runtime_status, etc. hit the Runtime server, which does not run in the Editor. - Async commands poll.
recompile→recompile_status,run_tests --async_tests→test_status. Never assume completion from the trigger call's response. - Target a specific instance with
--instance host:portor--project-path <path>when more than one is running.
Best Practice
When fixing a list of issues it's best practice to have a test case to make sure things are still working correctly. This might be a particular scene to open and start play mode, or a particular platform to build and run. If this isn’t present and there are no instructions, suggest a test case to the user and ask for confirmation. Run the test case before and after changes to make sure the project is still working.
As you work, make sure any changes are committed in alignment with user version control setup. Wherever possible, commit step-by-step, breaking things down into changes that a user can easily understand.
Recipe
- Make sure the project opens cleanly (with no compile or other errors in the Editor). If there are issues present, check with the user; they may know about them and want to ignore them. Run the test case and make sure you know what state it's in, fixing things if necessary.
- Commit any changes so that we start the upgrade process with clean version control.
- Open the project in the Unity Editor. Then use Unity CLI to run the audit command.
- Group the issues by file and by type.
- Choose a type of issue to work through one group or file at a time. 5.a. Default to fixing settings issues on assets or the projects by type. 5.b. Default to fixing code issues by file and subfolder. 5.c. However, it’s important to fix issues in human manageable and reviewable batches. 5.c.i. Making the same small change across a large number of files (for example, switching a boolean setting across many textures) is probably best done in one commit, or a commit per subfolder. 5.c.i.. When making code changes, the code should compile between each commit. 5.d. Make changes based on the recommendations from Project Auditor. Commit each change once there are no errors in the editor.
