CosmoSQLClient.CosmoKv.Cli 2.5.2

cosmokv — 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.

Usage

cosmokv                                    # REPL on a transient DB
cosmokv [--format=FMT] <database>          # REPL on <database>
cosmokv [--format=FMT] <database> [sql]    # one-shot SQL
cosmokv [--format=FMT] <database> -        # read SQL from stdin
cosmokv --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 ./mydb
cosmokv 2.5.0 — :help for commands, :quit to leave
cosmokv> CREATE TABLE Users (
    ...> Id BIGINT IDENTITY PRIMARY KEY,
    ...> Email NVARCHAR(256) NOT NULL);
0 rows affected.
cosmokv> INSERT INTO Users (Email) VALUES ('a@b'), ('c@d');
2 rows affected.
cosmokv> SELECT * FROM Users;
Id  Email
--  -----
1   a@b  
2   c@d  
(2 rows)
cosmokv> .quit

One-shot

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

cosmokv ./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 ./mydb -

Output formats

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

cosmokv --format=json ./mydb "SELECT Id, Email FROM Users" | jq '.[].Email'
cosmokv --format=csv  ./mydb "SELECT * FROM Users" > users.csv
cosmokv --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 ./prod-db ".dump" > snapshot.sql
cosmokv ./fresh-db - < snapshot.sql

Pipe a query result into another tool:

cosmokv --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 ./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 BackupAsync (in code) to a COSMOBAK snapshot.

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.