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 automateprepare/finalizeoutside an agent.
Run oy <command> --help for the exact flags supported by your installed version.
Setup and maintenance
| Command | Purpose |
|---|---|
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:
| Command | Purpose |
|---|---|
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.mdandoy-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
curl -fsSL https://oy.adonm.dev/install.sh | sh # prompt for mise scope
curl -fsSL https://oy.adonm.dev/install.sh | sh -s -- --global # global mise config
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
| Variable | Purpose |
|---|---|
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
| Path | Purpose |
|---|---|
~/.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:
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.
Prepared source may be sent to your configured model provider. oy does not upload reports or store provider credentials. See SECURITY.md.