OriginChainDB CLI command reference

This reference covers preview 0.6.0-dev.20261020. Management commands require the paired console and backend deployment. Start with the end-to-end guide; use Install and update for installation and signed-update commands.

Command map

Command family	Purpose
help, version	CLI usage and local executable version
init, doctor	Verified setup and online/offline diagnostics
login, whoami, logout	Personal management identity and local sign-out
credentials save, credentials remove	Store or remove a selected profile’s OS-vault credentials
db list, db show UUID	Organization-scoped database metadata
connection add, list, show, use, remove	Named engine profiles
health, server-version	Engine health and engine build metadata
sql, sql shell	One-shot SQL, files, binds, sessions and interactive input
schema list, schema show NAME	Schema identifiers and manifests
ui, ui --plain, ui --render	Interactive terminal workspace and offline home-screen rendering
graph query, neighbors, reverse, bfs, path, dijkstra	Cypher and graph traversals
vector list, put, query, explain, sparse, hybrid	Vector indexes, writes and similarity requests
fts search, fts index	Native table/field text search and document indexing
permission list, role list, create, update, delete	Organization capabilities and roles; requires org:admin
team list, invite, set-role	Members, pending invitations and role assignment; requires org:admin
search indices, query, count, mapping, settings, analyze	Elasticsearch-compatible reads for the selected tenant
completion bash, zsh, fish, powershell	Shell completion scripts
update	Signed release verification and executable replacement

Use oc COMMAND --help for flags. Database lifecycle changes, billing, bulk import, member removal and SQL autocomplete remain outside this preview. Browser-assisted login is implemented; production availability still depends on the paired deployment.

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.

Guided setup and diagnostics

Browser login and OS credential storage

With the paired console/backend release installed, run:

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

The CLI creates a random token locally, stores it in your OS vault, and opens Settings > Security. Compare the 12-character code, then approve in your signed-in console session. The URL contains a hash and display prefix, never the full token. Default approval grants database metadata reads for 30 days in the specified organization. Add --scope org:admin only for a separate administrative profile and explicitly acknowledge that scope in the console. It does not grant SQL access. The CLI polls identity, validates the organization, and saves the profile only after approval. The approval window is 10 minutes. --no-browser prints the URL for opening manually. This is browser-assisted token registration, not an OAuth provider integration. The endpoint must also serve the console; separate console/API origins are not supported by this first flow.

To save an existing environment token, use login ... --store, or:

oc --profile work credentials save --kind management
oc --profile development credentials save --kind engine
oc --profile work credentials remove --kind management

Saving verifies access first. Windows uses Credential Manager; macOS uses Keychain; Linux uses Secret Service through secret-tool (install libsecret-tools or your distribution’s equivalent and run an unlocked Secret Service). Secrets travel to OS helpers through stdin, never command-line arguments. There is no plaintext fallback. Headless servers can continue using environment credentials. A stored profile uses only its vault item, bound to its endpoint, organization/tenant, username, and credential variable names. Editing those fields invalidates it. logout deletes the stored management item and local profile; server revocation remains in console Settings > Security. Remove a saved engine credential before removing its connection. OS vault access can require an OS unlock prompt.

Native API references: Windows Credential Manager, Apple security utility, Secret Service tool.

Guided setup

Run oc init to enter a new profile name, engine origin, tenant identifier and database username. Set OC_BEARER and OC_DB_KEY through your secret manager or shell’s hidden input first. The wizard asks only for connection metadata. It checks engine health and schema metadata access before saving and selecting the profile. It preserves existing profiles and refuses to overwrite a name in the same family.

For scripts, supply the metadata and disable prompts:

oc --profile development init --non-interactive --endpoint https://db.example.com --tenant YOUR_TENANT_ID --db-user analyst_ro
oc --output table doctor
oc doctor --target engine --offline

--token-env, --key-env and --ca-cert customize credential references and TLS trust. Management setup uses a separate personal CLI token (OC_CLI_TOKEN) and the organization UUID from console settings:

oc --profile work init --kind management
oc --profile work doctor --target management
oc --output table db list

Management setup validates identity before saving, just like oc login. It does not automatically select organizations/databases or create an engine connection: the current API requires an explicit organization, and engine credentials and tenant identifiers are separate. Non-interactive setup defaults to profile default unless --profile or OC_PROFILE is provided. Prompts go to stderr; results go to stdout in the selected format. EOF, invalid metadata, failed access checks or a duplicate name leave existing configuration unchanged.

oc doctor checks version/platform, configuration, selected profile metadata, credential presence and CA settings. Online engine checks read health and schema metadata; management checks read identity and visible database metadata. It never executes SQL, changes grants, or writes configuration. Each failed check includes a suggested fix; raw server bodies and credential values are omitted. Metadata access does not prove SELECT permission on every table or search index.

By default, doctor checks each family’s current profile independently. With --profile NAME, it checks that name in whichever families contain it. Use --target engine or --target management to require a particular family. --offline makes no network requests and cannot validate token expiry, revocation, connectivity or server permissions. JSON diagnostics contain ok, offline and checks; table/CSV/JSONL render the check rows. Failures return the first check’s normal CLI exit code, with cancellation taking precedence. Use oc init --help and oc doctor --help for all options.

Console account and database discovery

After the paired backend and console feature are deployed, select your organization in the console and open Settings > Security > CLI access. Create a personal token with a name and an expiry (7, 30, or 90 days). Copy it once into your secret manager. Use your shell’s hidden input to set the process environment; avoid typing the token into command history. In PowerShell 7:

$env:OC_CLI_TOKEN = Read-Host 'Personal CLI token' -MaskInput

In Bash:

read -r -s -p 'Personal CLI token: ' OC_CLI_TOKEN; printf '\n'
export OC_CLI_TOKEN

Then use the control-plane origin and organization UUID shown by the console:

oc --profile work login --endpoint https://app.originchaindb.com --org YOUR_ORGANIZATION_UUID
oc whoami
oc --output table db list
oc db show DATABASE_UUID
oc logout

The default databases:read token permits only identity and database metadata reads in its bound organization. Current membership, roles, instance visibility, revocation and expiry are checked on each request. It does not authorize SQL, database lifecycle changes, billing, membership management, or credential administration. Create/revoke tokens in the console. Logout only forgets the local management profile; it does not revoke the token or clear your shell environment. Remove the environment variable when finished (Remove-Item Env:OC_CLI_TOKEN in PowerShell or unset OC_CLI_TOKEN in Bash). Revocation in the console blocks subsequent requests immediately.

Login saves only the origin, organization UUID, CA path and token environment variable name, after validating the server’s identity response. --token-env NAME selects another environment variable. --ca-cert FILE supports a private CA. Management profiles and engine profiles are separate; both honor --profile and OC_PROFILE, then their own saved current selection. The first management login defaults to profile default; every successful login selects that profile. Use oc --profile NAME whoami to select an existing profile for one invocation, or log in with that name again to make it current. Failed login leaves the config unchanged. Never use a console session cookie, organization API key or database key as a CLI token.

Configuration remains version 1 with optional management fields. Existing engine profiles are preserved. Older CLI binaries reject configurations containing these new fields; use a separate --config FILE if keeping both preview versions installed.

Connect to an engine

Provide your existing transport bearer and DB-user key through environment variables OC_BEARER and OC_DB_KEY, using your secret manager or shell’s secure input mechanism. The CLI never creates database credentials or links a database identity. Use an engine origin, not a console URL. HTTPS is required; HTTP is accepted only for loopback development endpoints.

oc connection add development --endpoint https://db.example.com --tenant YOUR_TENANT_ID --db-user analyst_ro
oc connection list
oc connection show development
oc health
oc server-version

The first connection becomes active. Add others with different names, select one with oc connection use NAME, or choose per invocation:

oc --profile development health
oc connection remove old-development

Use --token-env NAME / --key-env NAME on connection add for different credential environment variables. Profiles store only the variable names, never their values. --ca-cert /path/to/ca.pem adds a trusted CA for private TLS. Certificate verification is always enabled. Redirects are refused, so credentials are sent only to the configured origin.

Configuration lives in the OS user config directory under originchain/config.json (%AppData% on Windows, $XDG_CONFIG_HOME or ~/.config on Linux, ~/Library/Application Support on macOS). Override with OC_CONFIG or --config FILE. Selection order is --profile, then OC_PROFILE, then the saved current connection. Configuration precedence is --config, OC_CONFIG, then the OS default.

SQL and schemas

oc --output table sql --query 'SELECT * FROM products LIMIT 10'
oc sql --file query.sql
oc sql --query 'SELECT * FROM products WHERE id = $1' --params '[42]'
oc schema list
oc schema show default.products
oc --output csv sql --file report.sql > report.csv

Single quotes in the bind example preserve $1 in Bash and PowerShell. Use a file for queries containing shell-sensitive quoting. --file - reads stdin:

cat query.sql | oc sql --file -

PowerShell equivalent: Get-Content -Raw query.sql | oc sql --file -. Use the exact schema identifier from schema list with schema show; SQL’s default namespace appears as default.TABLE in the schema API.

For an explicit transaction, run oc sql --query BEGIN, read the returned session_id, and pass --session SESSION_ID on every following statement, including COMMIT or ROLLBACK. Each CLI invocation makes one request; it does not keep an implicit transaction alive between commands. SQL is sent as supplied and may change data. A timeout, interruption, or cancellation can leave the operation’s outcome unknown; the CLI does not retry it.

Interactive SQL shell

oc --profile development sql shell

Enter multiline SQL and finish with an unquoted semicolon. A complete input buffer is sent as one request, removing only the final unquoted submission semicolon; internal batch delimiters stay intact. Batches retain the server’s transaction semantics. Single/double/backtick quotes, dollar-quoted bodies, and line/nested block comments are recognized when deciding whether input is complete. This is a lexical boundary, not a SQL parser. Use --manual for procedure bodies with internal semicolons, then enter \g on its own line to submit the full buffer.

Results default to readable tables. Global --output json, jsonl or csv overrides that default. Prompts and status messages go to stderr. Commands:

Command	Action
\g	Submit the buffered SQL.
\r	Clear the buffer, including unfinished quotes.
\status	Report whether a transaction and pending input are tracked.
\help	Show shell help.
\q	Discard pending input and exit; roll back a known open transaction.

Successful BEGIN responses select the transaction session automatically. Later requests carry it until COMMIT or ROLLBACK confirms closure. A normal quit or EOF with no unfinished input rolls back a known open transaction and prints the server’s response. Server rules still determine what is transactional: operations the engine applies immediately cannot be undone by a client rollback.

SQL failures, incomplete batches, output errors, network uncertainty and Ctrl+C stop the shell without retry or automatic recovery requests. The last known transaction session is reported for explicit recovery using the existing oc sql --session ID command. EOF never submits unfinished SQL. Ctrl+C cancels the current request/input and exits with code 130; cancellation does not prove that the server stopped execution.

History is disabled by default. To save submitted SQL explicitly:

oc sql shell --history-file ./my-sql-history.jsonl

The file contains timestamped SQL verbatim, including literals, recorded before submission; an entry is not proof that execution succeeded. It contains no credential environment values unless those values were entered in the SQL itself. Files are limited to 10 MiB, use mode 0600 on Unix, and rely on directory/user ACLs on Windows. The shell does not reload or replay history, and its first version uses line input without arrow-key history navigation or SQL autocomplete.

Shell completion

Generate a completion script for PowerShell, Bash, Zsh or Fish. It suggests CLI commands, flags, enumerated values, and validated saved profile names. Completion reads only local configuration; it does not make server requests, retrieve credentials, complete SQL text or evaluate shell expressions.

PowerShell (current session):

oc completion powershell | Set-Content -Encoding utf8 ./oc-completion.ps1
. ./oc-completion.ps1

Bash:

oc completion bash > ./oc-completion.bash
source ./oc-completion.bash

Zsh (with its completion system initialized):

autoload -Uz compinit; compinit
oc completion zsh > ./oc-completion.zsh
source ./oc-completion.zsh

Fish:

oc completion fish > ./oc-completion.fish
source ./oc-completion.fish

These commands load completion for the current session. Add the source command to your shell’s profile yourself if you want it loaded on startup. Generated scripts invoke oc on PATH and honor OC_CONFIG or a preceding --config FILE for profile completion. For predictable completion use space-separated flags and literal config paths; filesystem-path completion is not provided.

Implementation references: Bash programmable completion, Zsh completion widgets, Fish commandline, and PowerShell argument completers.

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.

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 'OriginChainDB search'

Example search.json:

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

search count also accepts --file or --query. search analyze accepts --analyzer NAME. Commands require one concrete lowercase index name; requests are scoped to the selected tenant. Search returns the requested page only. The CLI does not automatically scroll, follow PIT cursors, or export an entire index.

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.

Output and scripting

Global options go before the command:

oc --profile development --output json --timeout 60s search query articles --file search.json

Format	Behavior
json (default)	Complete response, including result metadata and SQL batch outcomes.
jsonl	One SQL row or search hit per line; otherwise the complete object.
csv	SQL rows/search hits; nested values remain JSON in their cells.
table	Human-readable rows with terminal control characters escaped.

SQL tables and CSV preserve declared column order, including all-NULL columns. Absent cells render as null; untyped objects use sorted keys. Large JSON integer digits are preserved. JSONL emits server row objects as received, so missing SQL fields remain absent. For types and metadata, use json. Schema show returns a manifest string in the selected output format. UTF-8 input/request limit is 1 MiB; response limit is 32 MiB. Timeout defaults to 30 seconds (maximum 10 minutes).

Exit code	Meaning
0	Successful response or help/version.
2	Invalid arguments, configuration, or input.
3	Missing credentials, HTTP 401, or HTTP 403.
4	Other server error, invalid/oversized response, stopped SQL batch, unknown SQL outcome, or partial search.
5	TLS/network/timeout/redirect failure or output-write failure.
130	Cancelled request.

Partial search and stopped SQL batch responses are printed and return code 4; scripts must check the exit code before using the output. Server HTTP error bodies are suppressed because they may echo credentials or SQL; errors report the HTTP status. Successful response data is printed as requested. Profile metadata and query output may themselves be sensitive; choose their destination accordingly.