reference · cli

CLI (oc)

The oc command is a thin client around the OriginChain HTTP API. Use it for one-off queries, schema migrations, scripted backups, and anywhere you'd otherwise reach for cURL.

For application code, use one of the SDKs (Python, TypeScript, Go) - they handle retries and idempotency automatically. The CLI is for terminals and shell scripts.

1. Install.

# macOS / Linux - via the install script
curl -fsSL https://originchain.ai/install/cli.sh | sh

# Or download from GitHub releases:
# https://github.com/originchain/cli/releases

Windows binaries are available from the GitHub releases page. Most users run the CLI in WSL or Git Bash.

2. Configure.

The CLI reads three environment variables. Set them once per shell session.

export OC_HOST=acme.ap-south-1.db.originchain.ai
export OC_TENANT=acme
export OC_TOKEN=oc_live_xxxxxxxxxxxxxxxx

# Verify the connection
oc ping

oc ping hits the instance's health endpoint and prints the response time. If it fails, recheck your env vars and the dashboard's instance status.

3. Schemas.

# List schemas
oc schemas

# Register from a TOML file
oc schemas register --file orders.toml

# Show one schema
oc schemas get shop.orders

4. Rows.

# Insert a single row from JSON
oc rows put shop.orders --json '{"id":"o001","status":"paid","amount_cents":12900}'

# Read by primary key
oc rows get shop.orders o001

# Bulk import from an NDJSON file
oc rows put-batch shop.orders --file orders.ndjson --chunk 1000

--json can be replaced with --file path.json to read the row from disk. For very large imports, NDJSON via put-batch is the right choice.

5. Queries.

# SQL
oc sql "SELECT * FROM shop.orders WHERE status = 'paid' LIMIT 10"

# Natural language
oc ask "top 5 customers by total spend" --schema shop.orders

# Vector top-k from a JSON file containing the query embedding
oc vector topk shop.products --query-file query.json --k 10 --dim 768

# Full-text search
oc fts search shop.products description "carbon marathon" --mode bm25 --k 10

Query results print as JSON to stdout. Pipe through jq for pretty-printing or filtering. --format table renders a human-readable table.

6. Backups + PITR.

# Trigger a snapshot now (in addition to the automatic schedule)
oc snapshots create

# List snapshots
oc snapshots list

# Point-in-time restore preview (does not apply)
oc restore preview --to '2026-04-30T12:00:00Z'

Point-in-time recovery is a destructive operation. The CLI requires --confirm when actually applying a restore - preview always shows the timeline without touching data.

Built-in help.

Every command supports --help. The full command tree is also available as one page:

oc --help                  # top-level
oc rows --help             # one sub-command
oc rows put --help         # one leaf command