CLI reference

The ony command is the local connector. It enrolls a machine as a device, runs a self-hosted server on SQLite, wires your coding agent’s hooks, and toggles how Ony.ai gates you by phone. Run ony with no arguments (or ony --help) to see the full list.

Every command below is a real subcommand. Options shown are the ones you will actually reach for; run ony <command> --help for the complete signature.

Getting connected

ony init

One command to connect. Enrolls this machine (if it is not already enrolled), then wires Claude Code in the target project: it installs the /ony skill and the Claude Code hooks into the project’s .claude/ - PermissionRequest (the interactive permission gate), PreToolUse (decision-class events such as AskUserQuestion, plus the opt-in headless gate), and the lifecycle hooks.

Option	Default	Purpose
--url	http://127.0.0.1:8001	Ony.ai server to connect to
--email	prompted	Account email (only used if this machine is not yet enrolled)
--project	.	Project directory to wire your agent into
--force	off	Re-enroll even if this machine already has a device

Connect the current project

ony init

After ony init, restart your Claude Code session (or run /reload-plugins) so the /ony command loads. For OpenAI Codex, add ony hooks codex as a Codex PreToolUse hook. See the quickstart.

ony enroll

Enroll this machine as an Ony.ai device. ony init calls this for you; use enroll directly when you only want the device token, without wiring any agent.

Option	Default	Purpose
--url	http://127.0.0.1:8001	Ony.ai base URL
--email	prompted	Account email for this device
--name	hostname	Device name
--force	off	Enroll again even if this machine already has a device

The account password is never accepted on the command line (it would land in your shell history and process list). You are always prompted for it securely. Passing --password is refused with a non-zero exit.

ony enroll --url https://ony.example.com --email you@example.com

Modes

Set how Ony.ai gates the agent. By default these are project-scoped: the mode is written to the nearest project’s .ony/project.json, so every session in that project shares it and other projects are untouched. Add --global (or run outside any project) to set the machine-wide default in ~/.ony/config.json instead. A change takes effect on the next tool call. These mirror the /ony skill you can type inside Claude Code.

Command	Meaning
ony on	At the keyboard: phone me only for high-risk actions
ony away	Remote control: phone me for every actionable step (I left the keyboard)
ony here	Back at the keyboard: return to high-risk-only calls (same as on)
ony off	Ony.ai does nothing; tool calls use normal permissions

ony away            # phone me for everything in this project
ony on --global     # machine-wide default: high-risk only

ony status prints the mode currently in effect for the current directory. See the modes guide for how each mode composes with Claude Code’s own permission prompts.

Running a server

ony up

Run a full Ony.ai server locally on SQLite - no Docker, Postgres, or Redis (the Lite tier). It creates or upgrades a database under your Ony.ai home directory, then serves the dashboard and API. On first run, open the printed URL to create your account, then run ony init.

Option	Default	Purpose
--host	127.0.0.1	Address to bind (127.0.0.1 = this machine only)
--port	8001	Port to serve on
--reset	off	Delete the local database and start from an empty one

ony up

For the Docker (Postgres + Valkey) stack instead, see self-hosting.

ony daemon

Maintain the outbound WebSocket connection to the Ony.ai server. It reports connection status and observes pushed decision events (verifying each verdict’s signature and expiry for display only). The authoritative decision for a tool call is still taken by the gate hook over its own handoff-bound path. Press Ctrl-C to stop.

ony daemon

Attaching to other agents

ony opencode

Attach to a running OpenCode server and answer its permission asks by phone. Ony.ai attaches to your own opencode serve (it never spawns one), phones for a decision per the current mode (away = every ask, on = high-risk only, off = nothing), and replies allow or reject once per ask - never a standing “always” grant. Ctrl-C to detach.

Option	Default	Purpose
--url	http://127.0.0.1:4096	URL of the running opencode serve

ony opencode --url http://127.0.0.1:4096

Diagnostics

ony status

Show enrollment, connectivity, compatibility, and the current Ony.ai mode. Exits non-zero if the server reports a compatibility problem.

ony status

ony doctor

Diagnose the local install with one actionable line per check. Exits non-zero if any check fails.

Option	Default	Purpose
--project	.	Project directory whose Claude wiring to check

ony doctor

ony handoff

Trigger one handoff end to end and print the server’s decision. Useful as a smoke test after enrolling. The --risk hint is deliberately ignored by the server, which re-derives risk from the action type (see the policy model).

Option	Default	Purpose
--action	file_modify	action_type hint
--risk	low	Client risk hint (ignored by the server)
--choice	2	DTMF option to choose

ony handoff --action file_delete

Hooks

The ony hooks group installs the agent wiring and provides the handler endpoints the agents call. Most users only run install and uninstall; the per-event handlers are invoked by the agent, not by you.

ony hooks install

Install the /ony skill and the self-contained gate hooks into a project’s .claude/. This is what ony init runs after enrollment. Re-running it refreshes the wiring (stale entries are replaced, not duplicated).

Option	Default	Purpose
--project	.	Project directory to wire Claude Code into
--headless	off	This project runs agents headless (claude -p): gate via PreToolUse, since PermissionRequest never fires there

Set --headless only for projects that run Claude Code non-interactively. Interactive installs should leave it off so the gate inherits Claude Code’s own permission surface.

ony hooks install --headless

ony hooks uninstall

Remove Ony.ai’s hooks and generated files from a project’s .claude/. Only Ony.ai’s own entries and generated files are touched; hand-written hooks and a hand-written /ony skill are left in place.

Option	Default	Purpose
--project	.	Project directory to remove the Ony.ai wiring from

ony hooks uninstall

Agent handler endpoints

These read a hook event as JSON on stdin and write the decision to stdout. You wire them into the agent’s config once; the agent invokes them per event.

Command	Purpose
ony hooks claude	Handle a Claude Code gate event (PermissionRequest or PreToolUse)
ony hooks codex	Handle an OpenAI Codex PreToolUse event (deny-only, see below)
ony hooks event	Handle a lifecycle event (SessionStart, UserPromptSubmit, Notification, Stop, SubagentStop); forwards metadata to Ony.ai and never blocks the agent
ony hooks codex-app-server	Bridge a codex app-server approval channel to Ony.ai over stdio JSON-RPC (experimental)
ony hooks codex-app-server-proxy	Forwarding proxy for codex app-server so IDE and desktop approvals route through Ony.ai (experimental)

Codex is a deny-only beta

Codex’s PreToolUse hook honors only a deny verdict; allow and ask fail open. So on Codex, Ony.ai is a deny-only guardrail: a phone denial blocks the tool and an unresolved gate fails closed to deny, but Ony.ai cannot grant an approval (grants defer to Codex’s own approval flow). ony hooks codex requires Codex CLI 0.117 or newer. The codex-app-server bridge and proxy are experimental and pinned to specific Codex CLI versions.

See also

• Quickstart - go from install to first call
• Configuration - environment variables and config files
• Risk and policy model - how the server decides when to ring you