Gonavi CLI

GoNavi CLI

The GoNavi CLI is a standalone, headless binary for the GoNavi database client (Wails app). It queries and manages saved connections without the GUI and is built for scripting and AI agents: stdout carries machine-readable data (JSON/JSONL/CSV/Markdown), stderr carries JSON error reports, and every invocation exits with a stable exit code.

Install

Download the matching gonavi-cli_${VERSION}_${goos}_${arch} archive and gonavi-cli_${VERSION}_checksums.txt file from a GoNavi GitHub Release, verify the SHA256 checksum, extract the archive, then run:

gonavi version                         # -> {"version":"0.9.3"}

• The CLI is currently distributed through verified GitHub Release archives, not npm.
• GONAVI_CLI_RELEASE_BASE_URL may point at a mirror that preserves the same release asset names and checksum file. Release assets are named gonavi-cli_${VERSION}_${goos}_${arch}.tar.gz (darwin/linux) or .zip (win32), plus gonavi-cli_${VERSION}_checksums.txt.

Data root and environment

• Saved connections and the SQL audit log live under the GoNavi data root: GONAVI_DATA_ROOT if set, otherwise ~/.gonavi.
• --data-root PATH (before the command) overrides it for one invocation: gonavi --data-root /srv/gonavi-data list-connections.
• Never put secrets in argv — they show up in process listings. Pass them via environment variables (see Connection management) or a connection file.

Exit codes

Error contract

On failure the CLI writes one JSON object to stderr and exits nonzero:

{"ok": false, "code": "policy_denied", "message": "..."}

Common code values: usage, runtime_unavailable, connections_unavailable, connection_save_failed, connection_import_failed, connection_failed, connection_not_found, connection_ambiguous, connection_file_invalid, invalid_connection_input, missing_secret_environment, sql_file_unavailable, policy_denied, execution_failed, invalid_result, unsupported_result_shape, cancelled, outcome_unknown, output_failed, mcp_failed.

Error messages are redacted before they are printed, so they are safe to log.

Command reference

gonavi [--data-root PATH] list-connections
gonavi [--data-root PATH] connection <list|add|import>
gonavi [--data-root PATH] query (--conn ID_OR_NAME|--connection-file FILE) [--sql SQL|--sql-file FILE|SQL]
gonavi [--data-root PATH] export (--conn ID_OR_NAME|--connection-file FILE) --output FILE [--sql SQL|--sql-file FILE|SQL]
gonavi [--data-root PATH] batch (--conn ID_OR_NAME|--connection-file FILE) --file FILE --allow-write
gonavi [--data-root PATH] audit export --output FILE
gonavi [--data-root PATH] mcp <stdio|http|remote-config>

Every command supports --help. connection help and audit help also work. Help and version never start the database runtime.

version

gonavi version (or --version / -version) prints {"version":"..."}. It accepts no arguments.

list-connections / connection list

gonavi list-connections (alias connections, or connection list) prints one JSON object per line — each a SavedConnectionView (id, name, environmentType, config, secret flags like hasPrimaryPassword, ...).

Use this to discover the --conn selector for a later query:

gonavi list-connections | jq -r '.name + "\t" + .config.type + "\t" + (.config.host // "")'

connection add

gonavi connection add saves a connection. Flags:

--connection-params and --connection-params-env are mutually exclusive. On success the saved SavedConnectionView is printed as JSON on stdout.

export GONAVI_DB_PW='s3cret'
gonavi connection add --name analytics --type postgres \
  --host pg.internal --port 5432 --user etl --database warehouse \
  --password-env GONAVI_DB_PW --read-only

connection import

gonavi connection import --file FILE bulk-imports saved connections. The file is a JSON array of SavedConnectionInput, or an object with a connections array. Each imported connection is printed as JSON on its own line.

query

gonavi query --conn mydb "SELECT id, name FROM users LIMIT 10"
gonavi query --conn mydb --format md "SELECT * FROM orders WHERE status = 'open'"
gonavi query --conn mydb --sql-file query.sql --format json
gonavi query --connection-file /tmp/conn.json --database app "SELECT count(*) FROM events"

Flags: --conn ID_OR_NAME or --connection-file FILE (exactly one), --database DB (database/schema override), --sql SQL / --sql-file FILE / one positional SQL argument (exactly one), --format jsonl|json|csv|md|markdown (default jsonl), --allow-write (aliases: deprecated --allow-mutating), --query-timeout SECONDS.

--format behavior:

• jsonl (default): one JSON object per line — result_set events {"type":"result_set","resultSet":N,"columns":[...],"rowCount":N}, row events {"type":"row","resultSet":N,"data":{col:value}}, then a summary event {"type":"summary","success":true,"queryId":"...","resultSets":N,"rows":N}. Non-tabular statements (e.g. UPDATE) produce a single summary whose data carries metadata like {"affectedRows":3}.
• json: a single QueryResult envelope {"success":true,"message":"","data":[...],"fields":[...],"messages":[...],"queryId":"...","transactionId":"...","transactionPending":false}.
• csv / md: header + rows; require exactly one result set (multi-result-set queries fail with unsupported_result_shape). Markdown escapes | in cell values and renders newlines as <br>.

Mutating SQL (INSERT/UPDATE/DELETE/DDL) without --allow-write is rejected with exit 4 (policy_denied) — even on a writable connection. Read-only connections reject writes regardless of --allow-write.

export

gonavi export --conn mydb --sql "SELECT * FROM orders" --output orders.csv
gonavi export --conn mydb --sql-file q.sql --output report.xlsx --format xlsx
gonavi export --conn mydb "SELECT a, b FROM t" --output out.md --force

Flags: connection selection as in query, --output FILE (required), --format csv|json|md|html|xlsx (defaults to the output file extension), --columns a,b,c (projection), --xlsx-max-rows-per-sheet N, --force (overwrite an existing file), --query-timeout SECONDS.

On success prints the sanitized QueryResult JSON to stdout.

batch / exec-file

gonavi batch --conn mydb --file migrate.sql --allow-write
gonavi batch --conn mydb --file seeds.sql.gz --allow-write --transaction off --continue-on-error

Executes a SQL file (plain or .gz). Flags: connection selection as in query, --file FILE (or alias --sql-file FILE), --allow-write (required — batch is refused with exit 4 otherwise), --transaction single|off (default single; wraps the file in one transaction), --stop-on-error (default) / --continue-on-error (requires --transaction off), --job-id ID (durable job id), --max-statement-bytes N. On success prints the sanitized QueryResult JSON.

audit export

gonavi audit export --output audit.json
gonavi audit export --output audit.csv --from 2026-08-01T00:00:00Z --to 2026-08-13T23:59:59Z

Exports the SQL audit log. Flags: --output FILE (required), --format json|csv (default json), --force, and filters --connection-id, --database, --db-type, --status, --source, --search, --from, --to (RFC3339 or Unix milliseconds).

mcp

gonavi mcp stdio runs the MCP server over stdio; gonavi mcp http runs the Streamable HTTP server (see gonavi mcp --help for its options); gonavi mcp remote-config writes a remote MCP client config to stdout.

Connection selection

Two mutually exclusive ways to pick the target database:

• --conn ID_OR_NAME — resolve a saved connection by ID or exact name. Ambiguous names fail with connection_ambiguous (exit 3); unknown names with connection_not_found. List candidates with list-connections first.
• --connection-file FILE — a raw ConnectionConfig JSON file (see references/connection-config.md). The config is transient: it is never saved, must not contain id, and type is required. The file must be a regular file (not a symlink), at most 1 MiB, with unknown JSON fields rejected. Use this when the target database is not saved, or when you want credentials to live in a file rather than in a saved repository. Delete the file after use.

Data source types

--type accepts the normalized driver identifier; several friendly names are aliases (e.g. postgresql → postgres, doris → diros, kingbase8 → kingbase, intersystems → iris, intersystems-cache → cache, elastic → elasticsearch, chromadb → chroma, rocket-mq → rocketmq).

Built-in (always available): mysql, goldendb, postgres, oracle, redis, chroma, qdrant, milvus, rocketmq, mqtt, kafka, rabbitmq.

Optional (must be installed via the GUI Driver Manager or an agent): mariadb, oceanbase, diros (Doris), starrocks, sphinx, sqlserver, sqlite, duckdb, dameng, kingbase, highgo, vastbase, opengauss, gaussdb, iris, cache, mongodb, tdengine, iotdb, clickhouse, elasticsearch, trino, plus custom driver/dsn connections.

Workflows

1. Discover what is available: gonavi list-connections → pick name (or id).
2. Inspect data read-only (default): query --format md for a human-readable table, --format jsonl when streaming, --format csv for a file.
3. Write safely: always pass --allow-write explicitly, prefer --transaction control for multi-statement files, and double-check readOnly on the target connection.
4. Ad-hoc database without saving anything: write a connection file (permissions 0600), run query/export/batch with --connection-file, then remove the file.
5. Secrets: pass env var names (--password-env, --dsn-env, --uri-env, --connection-params-env), never literal values on the command line.

For the exact JSON shapes of ConnectionConfig and SavedConnectionInput, read references/connection-config.md.