OriginChainDB

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.sql

In 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.

Find the command you needEngine commands and management commands use different connection profiles.
  1. Choose the taskFind the command for queries, profiles or management.
  2. Select the right profileMatch the profile type to the command.
  3. Add flags and argumentsPut global flags before the command.
  4. Read the resultUse structured output and the exit code in scripts.

Find a command

TaskCommands
Inspect the CLIhelp, version
Set up and check accessinit, doctor, health, server-version
Save engine profilesconnection add, list, show, use, remove
Manage local credentialscredentials save, credentials remove
Query structured datasql, sql shell, schema list, schema show
Query relationshipsgraph query, neighbors, reverse, bfs, path, dijkstra
Query embeddingsvector list, put, query, explain, sparse, hybrid
Search table fieldsfts index, fts search
Search compatible indexessearch indices, query, count, mapping, settings, analyze
Access your accountlogin, whoami, logout, db list, db show
Manage roles and memberspermission list, role, team
Work interactivelyui, completion
Replace the executableupdate

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 --offline

Setup 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.

OptionEffect
--token-env NAME, --key-env NAMEChoose credential variable names.
--ca-cert FILETrust a private certificate authority.
doctor --target engine / managementCheck one connection family.
doctor --offlineCheck 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_UUID

Compare 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 management

Saving 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-version

The first connection becomes active. connection remove NAME removes its local configuration. HTTPS and certificate verification are required except for loopback HTTP; redirects are refused.

SettingSelection 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
OSPath
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.csv

Use 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 shell

An unquoted semicolon submits buffered SQL as one request. Use --manual for procedure bodies, then submit with \g.

Shell commandAction
\gSubmit the buffer.
\rClear pending input, including unfinished quotes.
\statusShow the tracked transaction and pending input.
\helpShow shell help.
\qDiscard 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.jsonl

History 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.ps1

Add 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.json

For 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}.

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 phrase

document.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.

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 list

Roles

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 KEYS replaces 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 --yes

Inviting 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.

FormatUse
json (default)Complete response, metadata and batch outcomes.
jsonlOne SQL row or search hit per line; otherwise the full object.
csvSQL rows or search hits; nested values stay JSON in cells.
tableReadable 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 limitValue
UTF-8 input/request1 MiB
Response32 MiB
Default / maximum timeout30 seconds / 10 minutes

These are CLI limits, not a database-wide capacity claim.

ExitMeaning
0Success, help or version.
2Invalid arguments, configuration or input.
3Missing credentials, HTTP 401 or HTTP 403.
4Server/protocol failure, oversized response, stopped SQL batch, unknown SQL outcome or partial search.
5Network, TLS, timeout, redirect or output-write failure.
130Canceled 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.

© 2026 Silicoyn Technologies Pvt Ltd

On this page