Agent & terminal CLI reference
Run structured read-only SQL, whole-database Markdown dictionaries, exports, backups, and MongoDB / Redis / Neo4j / Elasticsearch queries straight from your terminal or shell-capable AI agent.
Put dataomni on PATH and export the Agent Skill #
Terminal-native coding agents (such as Claude Code or Codex) and shell scripts can invoke dataomni cli directly without configuring an MCP server. Every command shares the exact same keychain grant, production invisibility, and read-only enforcement as dataomni mcp.
# Link dataomni onto PATH on macOS (Linux .deb/.rpm installs /usr/bin/dataomni)
ln -sf /Applications/DataOmni.app/Contents/MacOS/dataomni ~/.local/bin/dataomni
# Print the built-in SKILL.md guide for terminal agents
dataomni cli guide
Windows PowerShell & CMD exit-code note
Because dataomni.exe uses the Windows GUI subsystem, interactive shells return immediately unless stdout is piped. Pipe output in scripts (dataomni cli connections | Out-String) or run cmd /c start /wait to capture $LASTEXITCODE. AI agents already invoke subprocesses via pipes and are unaffected.
Relational inspection, query, export, and backup commands #
Pass connection names or IDs. For long SQL queries, pass - in place of the statement to read from standard input. Export and backup commands write only to brand-new target paths and never overwrite existing files.
| Subcommand | Behavior & limits |
|---|---|
| dataomni cli connections | Lists open non-production connections and their database types. |
| dataomni cli dictionary <conn> | Outputs a whole-database Markdown data dictionary (tables, columns, types, PKs, FKs). |
| dataomni cli schema <conn> [<table>] | Lists all tables and views, or columns, indexes, and foreign keys for one table. |
| dataomni cli ddl <conn> <table> | Prints the database's native CREATE definition (views on PostgreSQL; tables & views elsewhere). |
| dataomni cli query <conn> "<sql>" | Runs one read-only statement (default --limit 200, max 10000; default --timeout 30s). |
| dataomni cli explain <conn> "<sql>" | Returns the estimated execution plan without running ANALYZE. |
| dataomni cli export <conn> "<sql>" --out <file> | Streams full read-only results to a new CSV or JSON (--format json) file (default 300s timeout). |
| dataomni cli backup <conn> --out <path> | Runs a read-only logical/file backup (VACUUM INTO, DuckDB EXPORT, pg_dump, mysqldump, mongodump). |
| dataomni cli csv-preview <file> | Sniffs delimiter and UTF-8 / GB18030 encoding on a local CSV file and flags malformed rows. |
| dataomni cli test <conn> | Verifies read-only connectivity; attaches DNS / TCP port diagnosis on failure. |
$ dataomni cli dictionary shop_dev
$ dataomni cli query shop_dev "SELECT status, COUNT(*) FROM orders GROUP BY status" --limit 50
$ dataomni cli export shop_dev - --out /tmp/orders_summary.json --format json < report.sql
Dedicated NoSQL workspace commands #
Non-relational engines use purpose-built read-only subcommands rather than shoehorning everything into SQL strings:
# MongoDB (mongosh filter/pipeline syntax; $out and $merge refused at parse time)
dataomni cli mongo app_mongo collections
dataomni cli mongo app_mongo find shop.orders '{ status: "paid" }' --limit 20
# Redis (--db N goes before the operation; command checks COMMAND INFO readonly)
dataomni cli redis cache_dev --db 0 scan "session:*"
dataomni cli redis cache_dev get "session:42"
# Neo4j (EXPLAIN verifies query type == r before running in a read transaction)
dataomni cli neo4j graph_dev labels
dataomni cli neo4j graph_dev run "MATCH (u:User)-[:BOUGHT]->(p) RETURN u.id, p.sku LIMIT 25"
# Elasticsearch / OpenSearch (GET/HEAD or search POST such as _search, _count, _msearch)
dataomni cli es search_dev indices
dataomni cli es search_dev request POST /orders/_search '{"size":10,"query":{"match_all":{}}}'
JSON contract (schema: 1) and exit codes 0–4 #
Standard output always emits JSON with top-level "schema": 1 (pass --format table for human terminal tables; dictionary always emits Markdown). Errors go to standard error as {"schema": 1, "error": {"kind": "...", "message": "..."}} with deterministic exit codes so agents know whether to fix syntax or stop:
| Exit code | Category | Agent / caller action |
|---|---|---|
| 0 | Success | Parse stdout JSON (or Markdown from dictionary). |
| 1 | Database error or timeout | Read error.message and fix the SQL / query syntax or tighten filters. |
| 2 | Usage or not_found | Fix CLI flags, or ask the user to open the connection to agents in DataOmni. |
| 3 | Refused by read-only gate | Stop immediately — write statements, multi-statements, and $out/$merge are never allowed and no CLI flag overrides this. |
| 4 | Unavailable / keychain waiting | Network unreachable (inspect error.diagnosis) or macOS Keychain prompt waiting 10s for "Always Allow". |