oxy CLI is an optional companion for developers who want to work
with an Oxy project from the terminal — scaffolding a project, running
automations, validating config, and previewing it locally. You do not need
it to use Oxygen.
The CLI is for local development workflows. If you just want to ask questions of
your data, use the web app — skip this page.
Install
Run the install script. It downloads the right binary for your OS and architecture (macOS and Linux,x86_64 and arm64) and drops it on your
PATH:
OXY_VERSION:
/usr/local/bin when run as root, otherwise to
~/.local/bin (and adds it to your PATH for bash/zsh). If ~/.local/bin
isn’t already on your PATH, open a new shell after installing.
The install script supports macOS and Linux. Windows isn’t supported directly —
use WSL.
Verify
Update
Upgrade to the latest release in place:Basic commands
The CLI is self-documenting — runoxy --help, or oxy <command> --help for
any subcommand. The commands you’ll reach for most:
| Command | What it does |
|---|---|
oxy init | Scaffold a new Oxy project in the current directory |
oxy validate | Check config.yml, automations, and agents for errors |
oxy run <file> | Run an automation (.automation.yml) or a .sql file |
oxy start | Start Oxy locally with PostgreSQL in Docker (recommended) |
oxy serve | Start the Oxy web server (requires OXY_DATABASE_URL) |
oxy build | Build vector embeddings and sync integrations |
oxy mcp stdio | Start an MCP server so editors (Cursor, Claude Desktop) can use Oxy as a tool |
oxy update | Update the CLI to the latest release |
Create a project
Scaffold a new Oxy project in the current directory:Validate your config
Check yourconfig.yml, automation files, and agent definitions for syntax and
schema errors before running anything:
Run an automation
Pointoxy run at an automation or SQL file to execute it from the terminal:
Preview locally
oxy start brings up a local PostgreSQL container and the Oxy web server so you
can preview your project in the browser. It needs a Docker-compatible container
engine (Docker Engine, Docker Desktop, Rancher Desktop, Colima, Podman, …):
oxy serve instead if you’re supplying your own database via
OXY_DATABASE_URL, and oxy status to check what’s running.
Expose Oxy to your editor over MCP
Start an MCP server so MCP-compatible tools can query your project. This is the usual way to wire Oxy into Cursor or Claude Desktop:Next steps
Quickstart
Sign up and ask your first question in the web app
Connect to your editor with MCP
Use Oxy as a tool in Cursor and Claude Desktop