CLI command reference
Find commands for connection profiles, SQL, search, organization access and scripts.
Reference for preview 0.6.0-dev.20261020. Put global flags before the command, and use oc COMMAND --help for that command's options.
oc --profile development --output json --timeout 60s sql --file query.sqlIn the example, --profile chooses the connection, --output chooses the format and --timeout limits the request. sql is the command; --file is an option for that command. Keep this order when combining options.
- Choose the taskFind the command for queries, profiles or management.
- Select the right profileMatch the profile type to the command.
- Add flags and argumentsPut global flags before the command.
- Read the resultUse structured output and the exit code in scripts.
Find a command
| Task | Commands |
|---|---|
| Inspect the CLI | help, version |
| Set up and check access | init, doctor, health, server-version |
| Save engine profiles | connection add, list, show, use, remove |
| Manage local credentials | credentials save, credentials remove |
| Query structured data | sql, sql shell, schema list, schema show |
| Query relationships | graph query, neighbors, reverse, bfs, path, dijkstra |
| Query embeddings | vector list, put, query, explain, sparse, hybrid |
| Search table fields | fts index, fts search |
| Search compatible indexes | search indices, query, count, mapping, settings, analyze |
| Access your account | login, whoami, logout, db list, db show |
| Manage roles and members | permission list, role, team |
| Work interactively | ui, completion |
| Replace the executable | update |
Database lifecycle, billing, bulk import, member removal and SQL autocomplete are outside this preview's command set.
Terminal menu
oc ui opens the menu. Add --plain to disable color, or --render to print it offline. Enter a menu number; b goes back, q quits and :cancel cancels.
SQL, graph, vector and full-text actions use the engine profile. Roles, team and database discovery use the management profile. Changes require confirmation; SQL and Cypher can write data. Query history is off.
Set up and check a profile
Engine setup
Load OC_BEARER and OC_DB_KEY, then run oc init for prompts, or:
oc --profile development init --non-interactive --endpoint ENGINE_ORIGIN --tenant TENANT_ID --db-user DB_USER
oc --profile development --output table doctor --target engine
oc --profile development doctor --target engine --offlineSetup checks health and schema access before saving. Existing names are not overwritten and failed setup leaves configuration unchanged. Schema access does not imply table permissions.
| Option | Effect |
|---|---|
--token-env NAME, --key-env NAME | Choose credential variable names. |
--ca-cert FILE | Trust a private certificate authority. |
doctor --target engine / management | Check one connection family. |
doctor --offline | Check local configuration without a request. |
Browser approval and saved credentials
Use a console that supports this preview's CLI approval flow:
oc --profile work login --browser --endpoint https://app.originchaindb.com --org YOUR_ORG_UUIDCompare the 12-character code and approve within 10 minutes. Default approval is read-only database metadata access for 30 days. Use --no-browser to open the URL yourself. Console and management API must share an origin.
oc --profile work credentials save --kind management
oc --profile development credentials save --kind engine
oc --profile work credentials remove --kind managementSaving verifies access and uses the OS credential store. A saved item is bound to endpoint, identity and variable names; changing them invalidates it. Stored profiles do not silently fall back to environment credentials.
Management login and database discovery
For a compatible console's personal CLI token, load OC_CLI_TOKEN through a hidden prompt or secret manager. Then:
oc --profile work login --endpoint https://app.originchaindb.com --org YOUR_ORG_UUID
oc --profile work whoami
oc --profile work --output table db list
oc --profile work db show DATABASE_UUID--token-env NAME changes the token variable. login --store also saves it in the OS credential store. This management profile authorizes organization metadata, not database SQL. Run oc --profile work logout to remove its local login; revoke the remote token separately.
Engine connections and configuration
oc connection add development --endpoint ENGINE_ORIGIN --tenant TENANT_ID --db-user DB_USER
oc connection list
oc connection show development
oc connection use development
oc --profile development health
oc --profile development server-versionThe first connection becomes active. connection remove NAME removes its local configuration. HTTPS and certificate verification are required except for loopback HTTP; redirects are refused.
| Setting | Selection order |
|---|---|
| Config file | --config FILE, then OC_CONFIG, then the OS default. |
| Profile | --profile NAME, then OC_PROFILE, then the saved selection. |
Default config paths
| OS | Path |
|---|---|
| Windows | %AppData%/originchain/config.json |
| Linux | $XDG_CONFIG_HOME/originchain/config.json or ~/.config/originchain/config.json |
| macOS | ~/Library/Application Support/originchain/config.json |
Profiles store metadata and variable names, not credential values. Use a separate --config FILE with older CLI versions that cannot read management profiles.
SQL and schemas
oc schema list
oc schema show SCHEMA_IDENTIFIER
oc --output table sql --query 'SELECT $1 AS value' --params '[7]'
oc sql --file query.sql
oc --output csv sql --file report.sql > report.csvUse the identifier returned by schema list. --params accepts a positional JSON array. Single quotes protect $1 from the shell; a UTF-8 file avoids complex quoting. --file - reads standard input.
A SQL result can contain rows, metadata or write counts. An empty row list is not the same as a failed command; check the exit code and the full JSON outcome when scripting.
For one-shot transactions, run oc sql --query BEGIN and pass its returned session_id through --session SESSION_ID on every later statement, including COMMIT or ROLLBACK.
SQL shell and recovery
oc --profile development sql shellAn unquoted semicolon submits buffered SQL as one request. Use --manual for procedure bodies, then submit with \g.
| Shell command | Action |
|---|---|
\g | Submit the buffer. |
\r | Clear pending input, including unfinished quotes. |
\status | Show the tracked transaction and pending input. |
\help | Show shell help. |
\q | Discard input and exit; roll back a known open transaction. |
The shell tracks a successful BEGIN until confirmed COMMIT or ROLLBACK. Normal quit or EOF rolls back a known open transaction; DDL and other immediately applied operations may persist. EOF does not submit unfinished input.
On an error or Ctrl+C, the shell stops without retrying. Recover a reported session with oc sql --session ID. Cancellation does not prove a write stopped.
Output and opt-in query history
The shell defaults to tables; global --output json, jsonl or csv overrides it. Prompts go to stderr.
oc sql shell --history-file ./my-sql-history.jsonlHistory is off unless requested. It records submitted SQL verbatim, including literals, up to 10 MiB. Unix files use mode 0600; Windows uses directory ACLs. Submission is not proof of success, and history is never replayed.
Shell completion
Completion covers commands, flags and saved profiles, not SQL or file paths. Choose your shell and load the generated script:
oc completion powershell | Set-Content -Encoding utf8 ./oc-completion.ps1
. ./oc-completion.ps1Add the source line to your shell profile to load it on startup. Completion honors OC_CONFIG and --config FILE.
Graph and Cypher
These examples assume a social.users schema, a follows relation and the keys shown. Substitute your own graph data.
oc graph query --file query.cypher --schema social.users --params '{"name":"Alice"}'
oc graph neighbors social.users --rel follows --pk alice
oc graph reverse social.users --rel follows --pk carol
oc graph bfs social.users --rel follows --pk alice --max-depth 3
oc graph path social.users --rel follows --src alice --dst carol --max-depth 3
oc graph dijkstra social.users --rel follows --src alice --dst carol --weights '{}'Use exactly one of --query or --file; --file - reads stdin. --params is a JSON object of named Cypher values. --schema supplies the default for unlabelled patterns. Depth is 1–64, default 3; path checks reachability. Dijkstra takes engine edge-weight JSON. Cypher may write and is not automatically retried.
Vector operations
oc vector list
oc vector put embeddings --file vector.json
oc vector query embeddings --file nearest.json
oc vector explain embeddings --file nearest.json
oc vector sparse embeddings --file sparse.json
oc vector hybrid embeddings --file hybrid.jsonFor a three-dimensional cosine table, vector.json contains:
{"id":"one","embedding":[1,0,0],"dim":3,"metric":"cosine"}And nearest.json contains:
{"query":[1,0,0],"dim":3,"k":10,"metric":"cosine"}The CLI accepts --file FILE or --query JSON_OBJECT; --file - reads stdin. Supply actual embeddings that match the stored model, dimension and metric. Sparse and hybrid inputs use the engine's corresponding request objects. A successful empty write is printed as {"ok":true}.
Native full-text search
Use a table and field with oc fts:
oc fts index documents body --file document.json
oc fts search documents body --text 'account setup' --mode bm25 --limit 10
oc fts search documents body --text 'account AND setup' --mode boolean
oc fts search documents body --text 'account setup' --mode phrasedocument.json supplies the document ID and text:
{"doc_id":"one","text":"Account setup instructions"}BM25 is the default mode. --limit is 1–1000, default 10; search text is limited to 10,000 UTF-8 bytes. Indexing accepts --query JSON_OBJECT or --file FILE and is not automatically retried.
Elasticsearch-compatible search
Use one lowercase index name with oc search:
oc search indices
oc search query articles --file search.json
oc search count articles
oc search mapping articles
oc search settings articles
oc search analyze articles --text 'account setup'Example search.json:
{"size":10,"query":{"match":{"title":"account setup"}}}count also accepts --file or --query; analyze accepts --analyzer NAME. Results contain one page with no automatic scrolling or PIT traversal.
Organization roles and members
These commands require a compatible console, separate org:admin approval and the necessary role permissions. They do not grant engine access.
oc --profile admin login --browser --scope org:admin --endpoint https://app.originchaindb.com --org YOUR_ORG_UUID
oc --profile admin permission list
oc --profile admin role list
oc --profile admin team listRoles
Use capability keys from permission list and the returned role UUID:
oc --profile admin role create --name Analyst --permissions view-instances,read-data --yes
oc --profile admin role update ROLE_UUID --name 'Project analyst' --permissions view-instances,read-data --yes
oc --profile admin role delete ROLE_UUID --confirm ROLE_UUID--permissions KEYSreplaces the complete list; omit it to keep the list, or use--permissions=to clear it.- You can grant only capabilities you hold. Editing or deleting a custom role requires an owner.
- A role assigned to members cannot be deleted. Organization roles are separate from SQL grants.
Team members
oc --profile admin team invite --email colleague@example.com --role read_only --yes
oc --profile admin team set-role MEMBER_UUID --role ROLE_UUID --yesInviting sends email; membership starts after acceptance. Use member UUIDs from team list and either a built-in role key or custom-role UUID. The last owner cannot be demoted. Member removal uses the console.
Output, limits and exit codes
Choose table when reading output yourself and json when a script needs the complete outcome. Formats that keep only rows or hits can leave out information needed to diagnose a batch or partial result.
| Format | Use |
|---|---|
json (default) | Complete response, metadata and batch outcomes. |
jsonl | One SQL row or search hit per line; otherwise the full object. |
csv | SQL rows or search hits; nested values stay JSON in cells. |
table | Readable terminal output with control characters escaped. |
SQL tables and CSV keep column order; missing cells are null. Use JSON when you need metadata or exact integer digits. Schema show includes the manifest string.
| CLI limit | Value |
|---|---|
| UTF-8 input/request | 1 MiB |
| Response | 32 MiB |
| Default / maximum timeout | 30 seconds / 10 minutes |
These are CLI limits, not a database-wide capacity claim.
| Exit | Meaning |
|---|---|
0 | Success, help or version. |
2 | Invalid arguments, configuration or input. |
3 | Missing credentials, HTTP 401 or HTTP 403. |
4 | Server/protocol failure, oversized response, stopped SQL batch, unknown SQL outcome or partial search. |
5 | Network, TLS, timeout, redirect or output-write failure. |
130 | Canceled request. |
Partial search and stopped SQL batches can print results and still return 4. Check the exit code before using output. Never replay uncertain SQL simply because the command failed.