# 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.
## Adversarial review
Say `adversarial review, use Cursor` or `use Codex this time`. The host agent
asks you to choose a CLI and one of a few strong model/reasoning options on
first use, then remembers your choice in
`${XDG_STATE_HOME:-$HOME/.local/state}/oy/adversarial-review.json`.
It asks once about reasoning effort, recommending a supported high/xhigh level
and offering max when available. Say `use max this time` for a one-run override,
or `remember this` to save it. Models with fixed effort use `default`.
Say `switch reviewer` to change the saved reviewer. A fallback (for example,
“use Zen only when my OpenAI limit is hit”) runs only with your prior permission
and is reported along with the actual model and effort used.
The skill is a single Markdown file;
the host handles context gathering and the chosen CLI's invocation.
## 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`;
- `adversarial-review/SKILL.md`;
- `oy-setup/SKILL.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-*/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).