CosmoSQLClient.CosmoKv.Cli 6.48.26

cosmokv-sql — CLI shell for CosmoKv databases

Interactive command-line shell for CosmoKv embedded databases, in the spirit of sqlite3. REPL, one-shot SQL, stdin scripts, and four output formats. Ships as a dotnet global tool.

Install

dotnet tool install -g CosmoSQLClient.CosmoKv.Cli

After install, the binary is on PATH as cosmokv-sql.

Usage

cosmokv-sql # REPL on a transient DB
cosmokv-sql [--format=FMT] <database> # REPL on <database>
cosmokv-sql [--format=FMT] <database> [sql] # one-shot SQL
cosmokv-sql [--format=FMT] <database> - # read SQL from stdin
cosmokv-sql --help

<database> is either a bare directory path (e.g. ./mydb — sqlite3-style) or a full connection string (DataSource=./mydb;CreateIfMissing=false). The bare form is shorthand for DataSource=<path>;CreateIfMissing=true — the directory is auto-created if missing. Use the connection-string form when you want to require the database to already exist (set CreateIfMissing=false).

With no <database>, the REPL opens against a transient temp directory and removes it on exit — handy for trying things out. Use .open FILENAME from inside the REPL to switch to a persistent database (and keep your subsequent work).

REPL

Run with just a database path to drop into the interactive shell. Statements end with ; and may span multiple lines.

$ cosmokv-sql ./mydb
cosmokv-sql 1.5.0
Connected to './mydb'.
Enter ".help" for usage hints.
cosmokv-sql> CREATE TABLE Users (
 ...> Id BIGINT IDENTITY PRIMARY KEY,
 ...> Email NVARCHAR(256) NOT NULL);
0 rows affected.
cosmokv-sql> INSERT INTO Users (Email) VALUES ('a@b'), ('c@d');
2 rows affected.
cosmokv-sql> SELECT * FROM Users;
Id Email
-- -----
1 a@b 
2 c@d 
(2 rows)
cosmokv-sql> .quit

One-shot

Pass SQL as the last positional argument. Useful for shell scripting and ad-hoc queries.

cosmokv-sql ./mydb "SELECT COUNT(*) AS n FROM Users"

Stdin

Pass - instead of inline SQL to pipe a script in. The CLI splits on semicolons (outside string literals) and runs each statement in order.

cat schema.sql | cosmokv-sql ./mydb -

Output formats

--format=FMT (or .format FMT inside the REPL) selects how rows are rendered. Pipe to other tools for processing.

cosmokv-sql --format=json ./mydb "SELECT Id, Email FROM Users" | jq '.[].Email'
cosmokv-sql --format=csv ./mydb "SELECT * FROM Users" > users.csv
cosmokv-sql --format=tsv ./mydb "SELECT * FROM Users" | column -t -s $'\t'

REPL dot-commands

Dot-commands work only at the start of a fresh line (not mid-statement) and consume the whole line.

Examples

Snapshot a database to a script:

cosmokv-sql ./prod-db ".dump" > snapshot.sql
cosmokv-sql ./fresh-db - < snapshot.sql

Pipe a query result into another tool:

cosmokv-sql --format=json ./mydb "SELECT * FROM Events WHERE created_at > '2026-05-01'" \
 | jq 'group_by(.user_id) | map({user_id: .[0].user_id, n: length})'

Run a migration script:

cosmokv-sql ./mydb - < migrations/001_schema.sql

Limitations

• Statement splitting is lexical only — it understands single-quoted strings but not block comments or T-SQL GO. A trailing ; ends the current statement.
• No readline-style history or autocomplete; if you want those, wrap the CLI with rlwrap.
• .dump rewrites every row as a fully-qualified INSERT. For tables with millions of rows, prefer .backup FILENAME — it writes a COSMOBAK snapshot directly without the parse/encode round-trip.
• .backup only writes plaintext snapshots. To re-encrypt with a different key, use BackupAsync(stream, backupKey) in code.
• Opening an encrypted store from the shell requires a connection string with EncryptionKey=<base64> (32-byte AES-256 key, base64-encoded). Bare-path .open ./mydb opens unencrypted.

Related

• CosmoSQLClient.CosmoKv — the driver this CLI uses.
• CosmoKv — the underlying LSM-tree store.
• CosmoSQLClient-Dotnet — the umbrella repository with the rest of the family of drivers.