CLI Overview

oi is the command-line way into an oikapi instance — one of three, alongside the web interface and the REST API. It is the one to reach for when a change should be scriptable, reviewable, or run in CI; app development in particular is built around it.

Commands are grouped into authentication, data, development, and administration.

Installation

See Installation for download instructions.

Commands

Command	Description
`oi login [server-url]`	Authenticate with an oikapi instance
`oi logout`	Clear saved credentials
`oi whoami`	Show which principal the current credential authenticates as
`oi app`	Install, update, and inspect applications
`oi table`	List and describe tables
`oi record`	List, view, create, update, and delete records
`oi macro`	List, view, and apply macros
`oi admin user`	Manage users, roles, and invitations
`oi admin permission`	Manage table permissions
`oi admin config`	View or manage instance settings
`oi admin access`	Manage cross-app access integrations
`oi init <app>`	Create a new app from a template
`oi dev [app]`	Watch and auto-sync changes
`oi push <app>`	Push app changes to the server
`oi pull <app>`	Pull the latest app state from the server
`oi build <app>`	Build a `.oikapp` package
`oi validate <app>`	Validate app structure
`oi status <app>`	Compare local vs. server state
`oi test <app>`	Run an app’s file-based tests
`oi scenarios <app>`	Run rule scenario tests
`oi api`	Escape hatch — call an endpoint with no command of its own
`oi version`	Show version information

Run oi --help or oi <command> --help for the full, up-to-date list of subcommands and flags.

What the CLI does not do

oi reads and inspects schema (oi table list, oi table describe) but does not create tables or fields. Create them in the web interface, or declare them in an application you push with oi push — see App Development.

Authentication

# Login to an instance
oi login https://your-instance.example.com

# Login with OAuth2 browser flow
oi login --browser https://your-instance.example.com

# Verify your connection
oi whoami

Credentials are stored securely in your system keychain, so you only need to log in once.

`oi api` — the escape hatch

oi api sends an authenticated request to any endpoint, reusing your saved credentials. It exists for endpoints that have no command of their own.

Prefer a real command wherever one exists. oi record list crm.leads says what it means, validates its arguments, and formats its output; oi api GET /api/apps/crm/tables/leads/records does the same work while committing you to a URL shape. If you find yourself scripting oi api against an endpoint repeatedly, that is worth telling us about — it usually means a command is missing.

# An endpoint with no command of its own
oi api GET /api/health

# POST with a body
oi api POST /api/apps/myapp/unions '{"name": "work", "members": [{"table": "tasks", "type_value": "task"}]}'

# Pipe a body from stdin
echo '{"name":"work"}' | oi api POST /api/apps/myapp/unions