Docs / Developer / CLI
CLI
Install the OAIZ CLI on macOS, Linux or Windows, and manage workflows, knowledge, events, databases and apps from a terminal.
Install
The CLI runs on macOS, Linux and Windows, on x86-64 and Arm. The install command downloads the latest release, checks its SHA-256 checksum and installs it for your user.
curl -fsSL https://oaiz.io/install.sh | bashOn macOS and Linux the program goes in ~/.local/oaiz, with a link in ~/.local/bin. The installer says so if that folder is not on your PATH. On Windows the program goes in %LOCALAPPDATA%\oaiz\bin, and the installer adds that folder to your user PATH.
oaiz --version
oaiz loginThe installer ends with oaiz help start, which names the first commands. After you install the CLI, we strongly recommend that you install the OAIZ skill too. The skill teaches coding agents such as Claude Code, Codex and Cursor the CLI’s workflow, testing and data operations. oaiz skill install writes it to .claude/skills/oaiz and .agents/skills/oaiz in the current directory. With --global, it writes them to your home directory for every project. Run oaiz skill update --global after oaiz upgrade to keep them current. oaiz help agents reads the same guidance without installing it.
oaiz skill install --globalUpgrades
After a command, the CLI checks for a new release at most once a day. In a terminal, an install from the commands above then updates itself in the background after a successful command. A failed command only names the new release, because a server change can be the cause of the failure. Captured output never triggers an update: the CLI writes a JSON hint to stderr instead.
oaiz upgrade installs the latest release. It installs a release only when the OAIZ release key signed the release’s manifest and the archive matches that manifest. OAIZ_UPGRADE=notify announces releases without installing them. OAIZ_UPGRADE=off stops automatic checks, and so does running in CI.
oaiz upgrade --check
oaiz upgradeCommands and help
Commands use a resource followed by an operation. oaiz workflow list reads workflows. oaiz db query runs a database query. Help at each level lists the supported commands or flags.
oaiz --help
oaiz workflow --help
oaiz workflow run --help
oaiz statusSign in and automation
oaiz login opens OAIZ in a browser to approve the computer and sign in with your account’s usual authentication. oaiz login --no-browser prints a link and accepts the approval code for a remote terminal. oaiz status shows the account and host. oaiz logout ends the stored session. oaiz login --workspace signs in for the current directory and its subdirectories only, so each project can use its own account.
The approval page can sign in as you or as a service account you manage. Commands use that account’s access. Automation can set OAIZ_API_KEY_AUTH instead of using a browser session. An API key or credential helper takes precedence over a stored session.
The default API host is https://api.oaiz.io. OAIZ_BASE_URL and OAIZ_APP_URL select another API and app deployment. A stored session belongs to the host where it was created.
Workflows as editable documents
workflow get writes a JSON document containing the workflow and its jobs. workflow create and workflow edit read that format. Editing saves the whole workflow, so a job omitted from the document is removed. Keep an existing job’s uuid when changing it.
The following commands use workflow_id for a workflow identifier returned by workflow list. They export it, check a changed file without saving, then save a version on a branch named Reply change.
oaiz workflow get "$workflow_id" --file workflow.json
oaiz workflow edit "$workflow_id" --file workflow.json --dry-run
oaiz workflow edit "$workflow_id" --file workflow.json --new-branch "Reply change"workflow action list discovers the job types available to the organisation. workflow action get shows one type’s configuration, outputs and example. The document check reports invalid action settings and property references before saving.
Tests, live runs and deployment
workflow run tests by default. It can use a stored event, the latest matching event, an event JSON file or a provider’s example. A workflow starting with Schedule needs no input event.
oaiz workflow run "$workflow_id" --branch "Reply change" --latest-eventDefault tests do not publish events, integration writes stay off and approvals are auto-approved. Model calls and other action-specific effects still run. --integration-commands and --publish-events enable those effects independently. --live runs with real publication and integration writes.
workflow branch merge copies the branch’s workflows and jobs into main and deletes that branch. It merges the whole branch. --status live starts automatic execution on main. --yes is required when the command cannot ask for confirmation in a terminal. workflow logs shows execution history.
Knowledge and databases
knowledge get reads a document as Markdown. knowledge create and knowledge edit read a Markdown file. --branch and --new-branch keep edits separate from main. Editor-block JSON preserves colours and alignment that Markdown cannot represent.
Database commands manage Postgres schemas, migrations and rows. db query reads data with SQL. db execute changes rows. db migration apply changes structure. db types exports TypeScript table types for @oaiz/sdk.
oaiz db schema "$database_id"
oaiz db query "$database_id" --sql "SELECT
id,
status
FROM orders
LIMIT 10"
oaiz db types "$database_id" -o database.tsevent publish --body-file event.json publishes an event. integration get slack lists that provider’s actions and events. model list lists the models available to the organisation. These operations keep the same access rules as the API.
Output for scripts and coding agents
--json prints the command’s full result. --format jsonl prints one list item per line. Normal terminal output uses readable tables. When output is captured, the default is a short summary with the full result saved under .oaiz/output/. Hand-composed commands can project a list to items locally, so their output can differ from the raw HTTP envelope.
Primary list results use items. Cursor lists read one page by default. --all reads every page and --limit bounds the total returned. Request page sizes follow the endpoint budget automatically. --cursor resumes with the same filters and an unchanged token. A full collection omits hasMore and nextCursor. A cursor result ends with hasMore false and nextCursor null.
Saved agent output uses items for lists and data for resources. --fields and the preview change the display without trimming the saved full result. A saved single page is still only one page. Use --all when a script needs a complete inventory. A later-page error fails that read.
--body-file reads a JSON request from a file. --no-input refuses commands that would prompt. --yes supplies the confirmation for a command that requires it. Errors go to stderr and the command’s exit status tells a script whether it succeeded.