# CLI reference
> **New user?** You probably don't need this page yet. Most users just talk to their agent:
> `audit this repository with the oy-audit skill` — the skill calls these commands for you.
> Come here when you want exact flags, environment variables, or to automate `prepare`/`finalize` outside an agent.
Run `oy <command> --help` for the exact flags supported by your installed version.
## Setup and maintenance
| `oy setup` | Write the oy skills under `~/.agents/skills/` (or `OY_SKILLS_DIR`) and clean up legacy OpenCode plugin files/config entries. |
| `oy setup --workspace` | Write the skills under `.agents/skills/` in the current workspace instead. |
| `oy setup --dry-run` | Preview setup or removal without writing. |
| `oy setup --remove` | Back up and remove oy-owned skill files and legacy OpenCode config entries. |
| `oy doctor` | Show skills installation state, paths, and optional tooling. |
| `oy doctor --check` | Validate the skills installation and plugin-cache cleanup; exit nonzero on failure. |
| `oy doctor --install-missing` | Install optional tokei and Universal Ctags context helpers with mise. |
| `oy upgrade [--check\|--dry-run]` | Upgrade a mise-installed oy and refresh the skills. |
## Workflow commands
The oy skills run inside your agent (OpenCode, Cursor, Codex, Copilot, or
Gemini CLI). The deterministic evidence steps are CLI commands the skills
call:
| `oy audit prepare [OPTIONS]` | Prepare immutable audit evidence under `.oy/runs/<run-id>/`. |
| `oy audit finalize --run <run-id>` | Validate prepared evidence and write `ISSUES.md` or SARIF. |
| `oy review prepare [TARGET] [OPTIONS]` | Prepare workspace or `git diff TARGET` review evidence. |
| `oy review finalize --run <run-id>` | Validate prepared evidence and write `REVIEW.md`. |
`oy audit prepare` options: `--path PATH` (default `.`), `--out PATH`,
`--format markdown|sarif`, `--focus TEXT` (repeatable), `--max-chunks N`
(default `80`). `oy review prepare` adds an optional positional `TARGET`
branch/commit/ref; omit `--path` when a target is present.
Ask your agent to "audit this repository" or "review the diff against main";
it loads the matching oy skill, which runs prepare, reads every indexed
chunk, writes candidates, and finalizes the report. `oy enhance` remediation
is the `oy-enhance` skill: ask your agent to fix a finding by ID from
`ISSUES.md` or `REVIEW.md`.
Unknown oy commands are errors.
## Setup ownership and backups
Global setup uses `~/.agents/skills/` (the cross-agent Agent Skills location
read natively by OpenCode, Cursor, Codex, Copilot, and Gemini CLI), or
`OY_SKILLS_DIR` when set. Workspace setup uses `.agents/skills/` under
`OY_ROOT`. Setup writes:
- `oy-audit/SKILL.md`, `oy-review/SKILL.md`, `oy-enhance/SKILL.md`;
- `oy-setup/SKILL.md` and `oy-setup/oy-persona.md`.
Files written by setup carry `<!-- Generated by oy setup -->` and are
oy-owned; setup refreshes them in place and preserves user-modified files
without the marker.
Setup also migrates older oy releases: it strips the version-matched
`@oy-cli/opencode` plugin entry, obsolete oy plugin/command/MCP config
entries, and direct `oy`, `oy-*`, `oy.*` files under the OpenCode
`agents`/`commands`/`skills`/`plugins` directories from `opencode.json(c)`
and the platform OpenCode config directory. The downloaded OpenCode plugin
package cache (`<cache>/opencode/packages/@oy-cli/...` and the bundled
`@stablekernel/cursor-opencode-provider` fork) is deleted outright; it is a
regenerable cache.
Before changing existing owned files, setup creates a mode-`0700` backup
under the platform state directory (or local-data fallback). Unmodified
files remain byte-for-byte untouched. JSON/JSONC comments and formatting are
preserved in the backup, while changed configs are pretty-reserialized.
## Curl installer
```bash
curl -fsSL https://oy.adonm.dev/install.sh | sh -s -- --workspace # current mise.toml
```
The installer uses mise for oy and the optional tokei/Universal Ctags
context helpers, then runs `oy setup`. The default is interactive: choose
global config or the current workspace's `mise.toml`. Noninteractive
installs default to global.
## Environment variables
| `OY_ROOT` | Select the oy CLI workspace root and evidence/report path boundary. |
| `OY_SKILLS_DIR` | Override the global agent skills directory; default `~/.agents/skills`. |
| `OY_OPENCODE` | Select the OpenCode executable used for the optional post-setup location refresh; default `opencode2`. |
| `OY_OPENCODE_MODEL` | Record a model preference as `provider/model#variant` in prepared artifacts. |
| `OY_COLOR` | Set `auto`, `always`, or `never`. |
| `NO_COLOR` | Disable color output. |
| `OY_INSTALL_SCOPE` | Select `global` or `workspace` in `install.sh`; an explicit installer flag wins. |
| `OY_SKIP_SETUP` | Skip the skills setup in `install.sh`. |
## Files written by oy
| `~/.agents/skills/oy-*/SKILL.md` | Canonical oy skills (global setup). |
| `~/.agents/skills/oy-setup/oy-persona.md` | The oy agent persona used by the oy-setup skill. |
| `.agents/skills/oy-*/SKILL.md` | Canonical oy skills (workspace setup). |
| `ISSUES.md` | Default Markdown audit report. |
| `REVIEW.md` | Default code-quality report. |
| `oy.sarif` | Default SARIF audit output. |
| `.oy/runs/<run-id>/` | Prepared evidence and model-written candidates. |
| platform state/data directory | Private backup and prepared-run metadata. |
Report output paths must be workspace-relative and may not escape through parent traversal or symlinks.
## Advanced prepare/finalize protocol
The oy skills run these commands automatically:
```text
oy audit prepare [options]
oy audit finalize --run <run-id>
oy review prepare [target] [options]
oy review finalize --run <run-id>
```
Preparation writes an index, manifest, previous report when present, and ordered chunks under `.oy/runs/<run-id>/`. Finalization verifies the workspace, evidence hashes, current input, previous output, and candidate report/findings before writing the normalized report.
These commands are public for custom automation. Run their `--help` output before integrating them.
## Path and disclosure boundaries
Input scopes must resolve inside the workspace. The collector's exclusions and limits are documented in [Coverage and limits](workflows.md#coverage-and-limits).
Prepared source may be sent to your configured model provider. oy does not upload reports or store provider credentials. See [SECURITY.md](https://github.com/adonm/oy-cli/blob/main/SECURITY.md).