OriginChainDB CLI — end-to-end guide

oc provides an interactive terminal workspace and scriptable commands for SQL, graph/Cypher, vectors, native full-text search and Elasticsearch-compatible search. Named engine profiles control data access; separate management profiles provide console identity, database discovery and, with explicit administrative consent, organization roles and team invitations.

This walkthrough describes preview 0.6.0-dev.20261020. Follow the installation guide first. The command reference covers every command; test coverage distinguishes implemented features from verified production availability.

Before you begin

Have an existing database and permission to read the tables or indexes you will query. Setup does not create databases, database users, keys, grants or sample data automatically. Use only the query and write operations you are authorized to perform. Obtain these connection details from your administrator or console:

Data work	Console account and discovery
Engine HTTPS origin, tenant identifier, database username, transport bearer and database-user key	Console origin, organization UUID and a personal CLI token, or a signed-in console session for browser approval
Uses an engine profile, such as development	Uses a separate management profile, such as work
Authorizes SQL/search according to engine permissions	Defaults to identity and database metadata reads; organization administration requires separately approved org:admin

Do not substitute a console cookie, organization API key, or database key for a personal CLI token. A successful management login does not grant SQL access or create an engine connection.

1. Check your installation

Open a new terminal after installing:

oc version
oc help

The preview version should match the package you obtained. If the command is not found, follow the OS-specific PATH instructions in Install and update. Global flags such as --profile, --config and --output go before the command.

2. Set engine credentials securely

Load credentials using your secret manager or a hidden prompt. In PowerShell 7:

$env:OC_BEARER = Read-Host 'Engine transport bearer' -MaskInput
$env:OC_DB_KEY = Read-Host 'Database-user key' -MaskInput

In Bash:

read -r -s -p 'Engine transport bearer: ' OC_BEARER; printf '\n'
read -r -s -p 'Database-user key: ' OC_DB_KEY; printf '\n'
export OC_BEARER OC_DB_KEY

These prompt examples are specific to their named shell. For other shells, use your secret manager. Credentials are not command arguments and do not belong in configuration files or checked-in scripts.

3. Create and verify an engine profile

Replace ENGINE_ORIGIN, TENANT_ID and DB_USER with your connection metadata. ENGINE_ORIGIN is the engine’s HTTPS origin, not the console URL or a URL containing an API path.

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 health
oc --profile development server-version

init verifies health and schema metadata access before saving and selecting the profile. It refuses to overwrite an existing profile. For a guided setup, run oc init; the wizard asks for metadata, not secrets. To reuse an existing profile, skip init and run doctor against that profile.

Expected result: doctor reports successful configuration, credential, health, and schema checks. This proves metadata access; a specific table or index can still require a separate SELECT grant.

4. Save credentials for future terminals

With the environment credentials still present:

oc --profile development credentials save --kind engine

This verifies access and saves the credentials in Windows Credential Manager, macOS Keychain, or Linux Secret Service. Linux requires secret-tool and an unlocked Secret Service. There is no plaintext fallback. An OS unlock prompt may be required.

Remove the temporary variables, then verify access from a fresh process:

Remove-Item Env:OC_BEARER, Env:OC_DB_KEY
oc --profile development doctor --target engine

Bash equivalent:

unset OC_BEARER OC_DB_KEY
oc --profile development doctor --target engine

Stored credentials are bound to the profile’s endpoint, identity and credential variable names. Editing those fields invalidates the stored item. A stored profile does not silently fall back to environment values.

Interactive terminal workspace

oc ui
oc ui --plain
oc ui --render

oc ui opens a numbered terminal menu. Enter a number and press Enter; use b to return, q to quit, and :cancel to abandon a form. --plain disables color. --render prints the home screen and exits without making a network request.

Menu	Actions
1 · SQL	Submit a SQL statement
2 · Graph	Cypher, neighbors, reverse traversal, BFS, reachability and Dijkstra
3 · Vector	List indexes; put, query, explain, sparse and hybrid requests
4 · Full-text search	Native field search and document indexing
5 · Roles & permissions	List capabilities; list, create, edit or delete roles
6 · Team members	List members and pending invitations, invite, change a role
7 · Databases	List or inspect visible database metadata
8 · Select profiles	Select engine and management profiles independently
9 · Diagnostics	Check connection configuration and access

The menu uses your saved profiles. Select the engine profile for data queries and the management profile for organization actions. Opening the menu sends no background requests. Data and access changes ask you to type yes; EOF and cancellation do not submit unfinished forms. The UI saves no query history. SQL and Cypher execute as supplied and may write data. Use oc sql shell for multiline SQL and transaction tracking. The terminal UI does not draw a node-link graph or a vector plot; it renders query results as terminal tables.

5. Discover a schema and run SQL

oc --profile development schema list
oc --profile development schema show SCHEMA_IDENTIFIER

Use the exact identifier returned by schema list. For the following example, assume an existing readable products table with id and name columns. Replace it with a table from your database:

oc --profile development --output table sql --query 'SELECT id, name FROM products LIMIT 10'
oc --profile development sql --query 'SELECT id, name FROM products WHERE id = $1' --params '[42]'

Single quotes preserve $1 in Bash and PowerShell. For complicated quoting, save the query in a UTF-8 file named query.sql:

SELECT id, name FROM products LIMIT 10

Then run and export it:

oc --profile development sql --file query.sql
oc --profile development --output csv sql --file query.sql > products.csv

Expected result: rows in the requested format. SQL is executed as supplied and may change data. The CLI never retries SQL after a timeout or network failure; investigate an uncertain outcome before submitting it again.

6. Use the SQL shell and transaction tracking

oc --profile development sql shell

Enter SQL ending with an unquoted semicolon. For example:

BEGIN;
SELECT id, name FROM products LIMIT 10;
ROLLBACK;

The shell tracks a successful BEGIN session and sends it with subsequent statements until COMMIT or ROLLBACK confirms closure. Enter \status to see the tracked session, \r to discard pending input, and \q to quit. A normal quit rolls back a known open transaction. Server rules determine which operations can be rolled back.

Use --manual and a standalone \g to submit procedure bodies with internal semicolons. History is off by default. --history-file FILE explicitly saves submitted SQL verbatim; protect that file if SQL includes sensitive values. Errors and Ctrl+C stop the shell without replay. See transaction recovery.

7. Query a search index

oc --profile development search indices

Choose one concrete lowercase index name for which you have read permission. Assuming an existing articles index with a text field named title, save search.json:

{"size":10,"query":{"match":{"title":"OriginChainDB"}}}

Run:

oc --profile development search query articles --file search.json
oc --profile development search count articles
oc --profile development search mapping articles
oc --profile development search settings articles
oc --profile development search analyze articles --text 'OriginChainDB search'

The CLI returns the requested page. It does not automatically scroll, follow PIT cursors, or export an entire index. Check the exit code: a partial search response is printed but returns code 4.

Graph and Cypher

These commands use the selected engine profile and its database-user permissions. The examples assume an existing social.users schema with a follows relation and primary keys alice and carol. Substitute your own schema and keys.

oc graph query --query 'MATCH (n) RETURN n.uid' --schema social.users
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 '{}'

query accepts exactly one of --query or --file; --file - reads stdin. --schema supplies the default schema for unlabelled patterns. --params must be a JSON object; use parameter names that your Cypher statement references. bfs and path accept depths from 1 to 64, defaulting to 3. path checks reachability. Dijkstra accepts the engine’s edge-weight JSON object through --weights. Queries and traversal results are returned in the selected output format. Cypher can change data and is never 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

vector.json:

{"id":"one","embedding":[1,0,0],"dim":3,"metric":"cosine"}

nearest.json:

{"query":[1,0,0],"dim":3,"k":10,"metric":"cosine"}

Use the table, dimension and metric of your vector data. put writes an embedding; query returns nearest neighbors, and explain requests the engine’s explanation. The CLI does not generate embeddings. sparse.json and hybrid.json must contain the engine’s topk_sparse and topk_hybrid request objects for your configured data. All five table operations accept --query JSON_OBJECT as an alternative to --file FILE; --file - reads stdin. The CLI validates the JSON object and the engine validates its fields. A successful empty write response is rendered as {"ok":true}.

Native full-text search

Native FTS addresses a table and field. The separate oc search command family uses the Elasticsearch-compatible API and its index names.

oc fts index documents body --file document.json
oc fts search documents body --text 'terminal search' --mode bm25 --limit 10
oc fts search documents body --text 'terminal AND search' --mode boolean
oc fts search documents body --text 'terminal search' --mode phrase

document.json:

{"doc_id":"one","text":"OriginChainDB terminal search"}

Use your table and text field. index writes the document and accepts --query JSON_OBJECT or --file FILE (including - for stdin). Search defaults to BM25 and 10 hits. Supported modes are boolean, bm25 and phrase; --limit accepts 1–1000. Text is limited to 10,000 UTF-8 bytes. Server index configuration and grants determine which requests succeed; selecting a profile does not add permissions. Indexing is never automatically retried.

8. Add console login and database discovery

Deployment-dependent: this step becomes usable when your console has Settings → Security → CLI access and the management routes are enabled. Production rollout is still pending at this checkpoint. Engine steps above are independent.

oc --profile work login --browser --endpoint https://app.originchaindb.com --org YOUR_ORG_UUID

The CLI stores a newly generated credential in your OS vault, opens the console, and displays a 12-character code. Compare that code in the signed-in console and approve the matching organization. The URL carries a hash and display prefix, not the full token. Approval must happen within 10 minutes; the issued read-only management credential lasts 30 days. The console and API must use the same origin for this first browser flow.

Use --no-browser instead of --browser to print the approval URL for manual opening. If you already have a personal CLI token, load OC_CLI_TOKEN with hidden input and use login --store with the same endpoint and organization flags.

After approval:

oc --profile work whoami
oc --profile work --output table db list
oc --profile work db show DATABASE_UUID
oc --profile work doctor --target management

Expected result: your identity and only databases visible to you in that organization. Repeat whoami in a fresh terminal without OC_CLI_TOKEN to verify vault-backed access. Database discovery does not select an engine or retrieve its credentials; keep using the engine profile for SQL and search.

Organization roles, permissions and team members

Deployment-dependent: these commands require the paired backend and console release, including migration 0110_cli_organization_admin.sql after the personal CLI-token migration. They are implemented and locally tested in v0.6; production administration is not verified at this checkpoint.

Keep existing read-only discovery profiles. Approve a separate administrative profile with org:admin explicitly:

oc --profile admin login --browser --scope org:admin --endpoint https://app.originchaindb.com --org YOUR_ORG_UUID
oc --profile admin whoami
oc --profile admin permission list
oc --profile admin role list
oc --profile admin team list

Compare the terminal’s code in the signed-in console, confirm the organization, and acknowledge organization administration in the consent form. The default scope remains databases:read; existing tokens are never upgraded automatically. An org:admin token allows the administration routes but does not elevate the person’s current permissions. It does not grant engine-query access.

Create or change a role

Use the capability keys returned by permission list. For example:

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

Replace ROLE_UUID with the returned custom-role UUID. On update, --permissions replaces the entire list. Omit it to keep the current list; an explicit empty value (--permissions=) clears the list. --name can be updated independently. Unknown capabilities are rejected. Role creation cannot grant capabilities the caller lacks, and editing or deleting custom roles retains the console’s owner-only policy.

Delete an unused custom role by repeating its exact UUID:

oc --profile admin role delete ROLE_UUID --confirm ROLE_UUID

Roles assigned to members cannot be deleted. Organization roles are separate from engine SQL grants.

Invite a member or change their role

Use a built-in role key, such as read_only, or a custom-role UUID:

oc --profile admin team invite --email colleague@example.com --role read_only --yes
oc --profile admin team list
oc --profile admin team set-role MEMBER_UUID --role ROLE_UUID --yes

Replace the example email only when you intend to send an invitation. The result reports invitation/email-dispatch status; membership begins after acceptance. Opening the terminal menu does not send an invitation. Use the member UUID from team list when changing an existing member’s role. The last owner cannot be demoted. The server checks organization binding, active membership, current authority, token expiry and revocation on every request.

Create and revoke personal CLI tokens in console Settings → Security. oc logout removes the local profile and saved credential; it does not revoke the server token. Billing, password resets, token administration and member removal are outside this command set.

9. Add completion and automate safely

Generate completion for powershell, bash, zsh or fish; the reference has the exact load commands. Completion reads local metadata only and never queries a server or retrieves credentials.

For automation, use JSON output and check the process exit code before consuming results. In Bash:

if oc --profile development --output json sql --file query.sql > result.json; then
  printf 'Query succeeded\n'
else
  code=$?
  printf 'Query failed with exit code %s\n' "$code" >&2
  exit "$code"
fi

In PowerShell:

oc --profile development --output json sql --file query.sql > result.json
if ($LASTEXITCODE -ne 0) { throw "Query failed: $LASTEXITCODE" }

Do not retry a failed SQL command blindly. See output formats and exit codes.

10. Update or clean up

Follow verified updates and recovery once a signed release is published. The current preview has no embedded production update key.

To remove local credentials and profiles:

oc --profile development credentials remove --kind engine
oc connection remove development
oc --profile work logout

Run the management logout only if you created that management profile. If you also created admin, run oc --profile admin logout and revoke that token separately. Logout removes its local vault item and profile; revoke the personal token separately in console Settings → Security. Clear any environment credentials still set. Removing a connection does not delete the remote database or revoke its keys. Use the console or your administrator for those actions.

Keep the installed executable if you will use it again. To uninstall, remove only the installed oc/oc.exe and its known recovery files, and remove its PATH entry if unused. Preserve query exports and any profiles you still need. If you provisioned a disposable database or machine solely for testing, remove that exact resource through the service that created it and verify it no longer incurs charges.