Skip to content
MarykMaryk

CLI commands

Global commands

Section titled “Global commands”
  • help [command] — show available commands or details for one command.
  • connect — connect to a store.
  • serve — serve a store over HTTP.
  • disconnect — close the current store connection.
  • list — list available data models.
  • model [--with-deps] [--key-index-format] [<name|id>] — render the schema for a model.
  • model --all [--with-deps] [--key-index-format] — render schemas for all models.
  • add <model> <file> [--yaml|--json|--proto] [--meta] [--key <base64>] — add a new record from a file.
  • get <model> <key> [--include-deleted] [subcommand ...] — fetch a record and open the viewer, or run a record action inline.
  • undelete <model> <key> [--if-version <n>] — restore a soft-deleted record.
  • changes <model> <key> [options] — show versioned changes for a record.
  • scan <model> [options] — browse records in a scrolling list.
  • sql [options] SELECT ... or sql [options] --file <path> — run a bounded SQL query; --write enables row mutations.
  • migrations [status|pause|resume|cancel] — inspect or control managed migrations.

Quick example

Section titled “Quick example”
connect rocksdb --dir ./data
list
scan Client --show info.name.firstNames,info.name.familyName --order -info.name.familyName

One-shot mode

Section titled “One-shot mode”

Run a single command without the interactive UI:

maryk --connect rocksdb --dir ./data --exec "list"
maryk --connect rocksdb --dir ./data --exec "model Client"
maryk --connect rocksdb --dir ./data --exec "add Client ./client.yaml"
maryk --exec "serve rocksdb --dir ./data --port 8210"

Notes:

  • --connect is optional for commands that do not require an existing connection (for example serve or help).
  • --exec is parsed like CLI input (quotes supported).
  • Commands that open interactive viewers (get without a subcommand or connect without args) are rejected in one-shot mode.
  • scan in one-shot mode returns a single page (respecting --limit) as plain output.
  • Use get <model> <key> <subcommand ...> to run save, load, set, unset, append, remove, or delete without entering the viewer.

SQL

Section titled “SQL”

SQL runs against the connected store. The command preserves SQL string literals, quoted names, and comments:

sql SELECT name FROM Person WHERE name LIKE 'A%' ORDER BY name LIMIT 20
sql SELECT category, COUNT(*), SUM(amount) FROM Invoice GROUP BY category
sql --file ./report.sql
maryk --connect rocksdb --dir ./data --exec "sql SELECT COUNT(*) FROM Invoice"

Options: --snapshot, --to-version <n>, --include-deleted, and --no-table-scan. Choose at most one consistency option (--snapshot or --to-version). Use -- before SQL that starts with a line comment, for example sql -- -- report followed by a newline and SELECT 1; a SQL file can start with comments directly. Versioned reads require retained history and an authoritative snapshot provider. Table scans are enabled by default in the CLI, with at most 10,000 result rows and 8 MiB of logical buffered data. Query files are limited to 64 KiB. Output uses tab-separated columns, quotes strings, renders SQL NULL explicitly, and escapes control characters.

Parameters are available through the Kotlin SQL API. In the CLI, use SQL literals or a file. Add --write to execute bounded INSERT, UPDATE, DELETE, UNDELETE, or DELETE HARD statements:

sql --write INSERT INTO Person (name, age) VALUES ('Ada', 37)
sql --write UPDATE Person SET nickname = NULL WHERE __key = '<encoded-key>' AND __version = 12345
sql --write --file ./mutation.sql

Each statement uses a serializable autocommit transaction, supports bounded predicates and RETURNING, and commits all affected rows together. Optional scalar properties can be set to NULL. The CLI prints confirmed affected rows and structured failures. An uncertain commit retains its transaction in the interactive session; use sql --resolve-commit before another write. A one-shot process cannot retain the handle after exit, so an uncertain status is not proof of rollback. --write cannot be combined with --snapshot, --to-version, or --include-deleted. Schema changes remain Maryk operations. See the SQL module for types, guards, limits, and supported syntax.

SQL transaction commands retain a session on the current interactive connection. Use sql --write BEGIN, followed by queries and --write mutations, then sql --write COMMIT or sql --write ROLLBACK. SAVEPOINT, ROLLBACK TO and RELEASE are supported. Querying staged data does not require —write. Mutations require —write even inside an active transaction and are rejected before execution otherwise. Disconnect rolls back staging; resolve uncertain commits before disconnecting or replacing the connection. BEGIN fixes the table-scan policy for that transaction. One-shot transaction commands are rejected because they cannot retain a session.

See the query reference for supported SQL syntax, including catalog discovery, windows and collection expansion, and the write reference for joined mutations and conflict handling.

Connect

Section titled “Connect”
connect rocksdb --dir /path/to/rocksdb
connect foundationdb --dir maryk/app/store [--cluster /path/to/fdb.cluster]

Serve

Section titled “Serve”

Serve a local store over HTTP (Ktor):

serve rocksdb --dir ./data --host 127.0.0.1 --port 8210
serve foundationdb --dir maryk/app/store --cluster /path/to/fdb.cluster --port 8210
MARYK_BEARER_TOKEN=replace-with-a-secret maryk serve rocksdb --dir ./data --host 127.0.0.1 --bearer-token-env MARYK_BEARER_TOKEN
serve rocksdb --dir ./data --host 127.0.0.1 --bearer-token-file ./maryk-token
printf '%s' 'replace-with-a-secret' | maryk serve rocksdb --dir ./data --host 127.0.0.1 --bearer-token-stdin

Config file:

store: rocksdb
dir: ./data
host: 127.0.0.1
port: 8210
bearer-token-env: MARYK_BEARER_TOKEN
serve --config ./serve.conf

Use exactly one of --bearer-token-env &lt;name&gt;, --bearer-token-file &lt;path&gt;, or --bearer-token-stdin (the same bearer-token-env, bearer-token-file, and blank bearer-token-stdin: config keys are supported). --bearer-token &lt;token&gt; remains available for compatibility but warns because command-line arguments can be visible to other local users and process monitors.

Notes:

  • Serves the Remote HTTP protocol.
  • serve blocks the CLI session until the server is stopped.
  • serve is available in JVM and native desktop binaries.
  • Loopback is the default and requires no authentication.
  • Non-loopback plaintext binds require the explicit unsafe --allow-insecure-remote-binding opt-in, even with --bearer-token.
  • Bearer authentication does not encrypt traffic; use TLS termination or SSH tunneling outside localhost.

Model

Section titled “Model”
model [--with-deps] [--key-index-format] [<name|id>]
model --all [--with-deps] [--key-index-format]

Options:

  • --with-deps includes dependent definitions.
  • --key-index-format prints key/index format details.
  • --all renders every model in the connected store.

When the output viewer is shown, save supports YAML/JSON/PROTO, plus Kotlin output:

  • save &lt;dir&gt; --kotlin --package &lt;name&gt; (generates Kotlin files)
  • save &lt;dir&gt; --no-deps (export without dependencies)

Multi-file saves (Kotlin or --meta) publish a complete revision under &lt;dir&gt;/.maryk-export/ by default. Use --legacy-direct only for consumers that require files directly in &lt;dir&gt;.

Migrations

Section titled “Migrations”
migrations status
migrations pause <model>
migrations resume <model>
migrations cancel <model> [reason]

The CLI migration command works with local RocksDB/FoundationDB stores. Remote Store authorization and migration administration are available to programmatic server integrations, but the CLI currently has no Remote migration-admin connection path. Status includes phase, attempt, estimated completion time, and counters when available.

Add

Section titled “Add”

Add a new record from a file:

add <model> <file> [--yaml|--json|--proto] [--meta] [--key <base64>]

Examples:

add Client ./client.yaml
add Client ./client.meta.yaml --meta
add Client ./client.yaml --key AbCdEf123
add Client - --yaml < ./client.yaml

Notes:

  • Format defaults to YAML.
  • --meta expects a metadata file saved via save --meta; its key is used (version/deleted flags are ignored).
  • If --key is omitted, the key is derived from the values (UUIDv4/UUIDv7 keys generate a new key).
  • --key must match the metadata key when --meta is used.
  • YAML/JSON files can contain a list of objects to add multiple records.
  • Use - as the file path to read from stdin.

Reference paths

Section titled “Reference paths”

Many commands take property references (for set, show, select, order, etc.). Use dot notation:

  • info.name.firstNames — nested fields
  • addresses.@0 — list item at index 0
  • addresses.* — list/map wildcard
  • moment.*ShiftMetaDataType.executor — multi-type list/map with type name

For select, nested paths such as embeddedValues.value build a graph. Selecting an entire parent includes its children, even when a child is also listed. Use map[key] for graph map-entry selection. Comma-separated path lists preserve commas inside brackets: --select "entries[a,b].first,details.second". The App and CLI share the same parser. For order, $key selects primary-key order and -$key reverses it.

Get viewer

Section titled “Get viewer”

When get returns data, you enter a viewer with scrolling output.

Commands:

  • save &lt;dir&gt; [--yaml|--json|--proto] [--meta] [--legacy-direct] — export the record.
  • load &lt;file&gt; [--yaml|--json|--proto] [--if-version &lt;n&gt;] [--meta] — apply values from a file.
  • set &lt;ref&gt; &lt;value&gt; [--if-version &lt;n&gt;] — set or replace a value.
  • unset &lt;ref&gt; [--if-version &lt;n&gt;] — clear a value.
  • append &lt;ref&gt; &lt;value&gt; [--if-version &lt;n&gt;] — append to a list or add to a set.
  • remove &lt;ref&gt; &lt;value&gt; [--if-version &lt;n&gt;] — remove from a list or set.
  • delete [--hard] — soft delete (default) or hard delete.
  • undelete [--if-version &lt;n&gt;] — restore a soft-deleted record.
  • close (when opened from a scan) — return to the scan list.
  • q|quit|exit — leave the viewer.

If the viewer was opened from a scan, close returns to the scan list.

One-shot examples:

maryk --connect rocksdb --dir ./data --exec "get Client AbCdEf123 save ./out --yaml"
maryk --connect rocksdb --dir ./data --exec "get Client AbCdEf123 set info.name.nickname \"Captain Jasper\""

Notes:

  • Values are parsed as Maryk YAML scalars for the referenced type.
  • Strings do not require quotes, but quoting is recommended for spaces or YAML special characters.
  • --if-version applies optimistic concurrency checks.
  • save --meta stores the record metadata; load --meta uses metadata from the file (key/version).
  • append/remove only support list or set references.
  • Use get --include-deleted to access soft-deleted records.
  • Use - as the load file path to read from stdin.

Scan viewer

Section titled “Scan viewer”

The scan viewer shows one record per line, with a leading &gt; for the selected row. Additional pages resume with the datastore-issued opaque cursor, so index-ordered paging stays stable when the previous boundary record changes.

Navigation:

  • Up/Down: move the selection
  • PgUp/PgDn: page
  • Home/End: jump to start/end

Commands:

  • get — open the selected record in the viewer.
  • show &lt;ref,...&gt; — choose fields to display (also updates the select graph).
  • filter &lt;expr&gt; — add another where clause (Maryk YAML format).
  • save &lt;dir&gt; [--yaml|--json|--proto] [--meta] [--legacy-direct] — export the selected record.
  • load &lt;file&gt; [--yaml|--json|--proto] [--if-version &lt;n&gt;] [--meta] — apply values to the selected record.
  • delete [--hard] — soft delete (default) or hard delete.
  • undelete [--if-version &lt;n&gt;] — restore a soft-deleted record.
  • close — leave the scan viewer.
  • q|quit|exit — leave the scan.

Filtering examples (Maryk YAML tags):

scan Client --where "!Equals { info.name.familyName: \"Smith\" }"
scan Client --where "!And
  - !Equals { info.status: \"Active\" }
  - !GreaterThanEquals { info.age: 21 }"

Ordering examples:

scan Client --order info.name.familyName
scan Client --order -info.name.familyName
scan Client --order info.name.familyName:desc

Scan options (from the scan command):

  • --start-key &lt;base64&gt;
  • --limit &lt;n&gt;
  • --include-start / --exclude-start
  • --to-version &lt;n&gt;
  • --include-deleted
  • --where &lt;expr&gt;
  • --order &lt;ref,...&gt;
  • --select &lt;ref,...&gt;
  • --show &lt;ref,...&gt;
  • --max-chars &lt;n&gt;

Undelete

Section titled “Undelete”
undelete <model> <key> [--if-version <n>]

Restores a soft-deleted record.

Changes

Section titled “Changes”
changes <model> <key> [--from-version <n>] [--to-version <n>] [--limit <n>] [--include-deleted]

Examples:

changes Client AbCdEf123 --from-version 10
changes Client AbCdEf123 --include-deleted --limit 100

Notes:

  • --limit caps the number of versions returned for this key (default 1000).
  • Use --from-version/--to-version to narrow the history.