CLI: eelgrass

Dev CLI from crates/eelgrass-cli. The Cargo package is eelgrass-cli; the installed binary name is eelgrass.

Invoke from a checkout with Cargo (recommended while pre-alpha):

cargo run -p eelgrass-cli -- <command> …

After cargo build -p eelgrass-cli, the same argv works as target/debug/eelgrass (or target/release/eelgrass). Examples below use the Cargo form; omit cargo run -p eelgrass-cli -- when calling the binary directly.

Bare invocation (no command, or unknown usage) prints the help text and exits 0:

eelgrass pre-alpha
usage:
  eelgrass lex "<Eelgrass Lang query>"
  eelgrass typecheck <schemas.eel> --query "<Eelgrass Lang query>"
  eelgrass typecheck-queries <schemas.eel> <queries.eel>
  eelgrass run <db_dir> <schemas.eel> <queries.eel>
  eelgrass serve <db_dir> <schemas.eel> [--ui <dist>] [--port N] [--token T]
  eelgrass studio <db_dir> <schemas.eel> [--ui <dist>] [--port N] [--token T]
  eelgrass compact <db_dir> [tenant]

Capability honesty: see Status. For the HTTP surface behind serve / studio, see HTTP API. Studio UI: Studio. Ops topics (layout, health, compact, CDC): Operations.

---

Database directory

run, serve, studio, and compact take a db_dir path as the first positional after the subcommand. The engine opens (or creates) that directory for durable pages, WAL, and Meta.

Meta upgrade warning. After an incompatible Meta format change, recreate the directory (delete or move the old db_dir and open a fresh one). Do not expect silent in-place migration of an old on-disk layout.

---

lex

Dump lexer tokens for a single query string.

Synopsis

cargo run -p eelgrass-cli -- lex "<Eelgrass Lang query>"

Args

Arg	Required	Description
<query>	yes	Query / fragment text (one argv string)

Behavior

Prints one line per token: line:col, token kind, and lexeme text. Exits 0 on success. Requires at least three argv entries (eelgrass lex <query>).

Example

cargo run -p eelgrass-cli -- lex "users |> filter active == true"

---

typecheck

Parse and typecheck one query against a schema file. Emits a JSON result on stdout (from eelgrass_lang::json::typecheck).

Synopsis

cargo run -p eelgrass-cli -- typecheck <schemas.eel> --query "<Eelgrass Lang query>"

Args / flags

Arg / flag	Required	Default	Description
<schemas.eel>	yes	—	Schema source file
--query	yes	—	Literal flag; must be argv immediately after the schema path
<query>	yes	—	Query text following --query

The dispatcher matches exactly: typecheck <schemas.eel> --query <query> (five or more argv slots).

Exit

• 0: typecheck produced no errors
• 1: cannot read schema file, or typecheck reported errors

Example

cargo run -p eelgrass-cli -- typecheck examples/demo_schema.eel \
  --query "users |> select { name }"

---

typecheck-queries

Typecheck named query declarations in a queries file (D15). Also loads any use schema "…" paths relative to the queries file, appending those schema sources (skipping the path when it resolves to the same file as <schemas.eel>).

Synopsis

cargo run -p eelgrass-cli -- typecheck-queries <schemas.eel> <queries.eel>

Args

Arg	Required	Description
<schemas.eel>	yes	Primary schema file
<queries.eel>	yes	File with named-query decls (and optional use schema)

Behavior

Prints JSON from typecheck_named_queries_json. Exits 1 if the schema or queries file cannot be read, a use schema path cannot be resolved/read, or any file-level / per-query typecheck error is present; otherwise 0.

Example

cargo run -p eelgrass-cli -- typecheck-queries \
  examples/demo_schema.eel examples/queries/users.eel

---

run

Open (or create) a database directory, load schemas, parse a queries file, and execute every supported top-level statement.

Synopsis

cargo run -p eelgrass-cli -- run <db_dir> <schemas.eel> <queries.eel>

Args

Arg	Required	Description
<db_dir>	yes	Durable DB directory (pages + WAL + Meta)
<schemas.eel>	yes	Schema source. Parsed, registered, indexes ensured.
<queries.eel>	yes	Program of statements to execute

What run executes

For each top-level AST node in the queries file:

Node	Behavior
Query (pipeline)	Typecheck, then run_query; print insert/select/update/delete rows
atomic { … }	Typecheck every inner query, then run_atomic; print each sub-result
Tenant op	db.execute_tenant_op (create / fork / snapshot / suspend / delete, etc.)
Other nodes	Ignored

Schema parse/registration failures abort before execution. Per-query typecheck or runtime errors are printed and counted; the process continues with remaining statements. A final stderr line reports how many statements ran.

Exit

• 0: all executed statements succeeded (no typecheck/runtime errors)
• 1: I/O / open / schema / parse failure, or any statement had errors

Example

cargo run -p eelgrass-cli -- run ./mydb \
  examples/demo_schema.eel examples/demo_queries.eel

---

serve

Local HTTP/1.1 API (stdlib-only) for Studio and any HTTP client. Binds loopback only. Runs until the process is killed.

Synopsis

cargo run -p eelgrass-cli -- serve <db_dir> <schemas.eel> \
  [--ui <dist>] [--port N] [--token T]

Args / flags

Arg / flag	Required	Default (from source)	Description
<db_dir>	yes	—	Durable DB directory
<schemas.eel>	yes	—	Schema loaded at process start
--ui <dist>	no	Probe (see below)	Directory containing Studio index.html
--port N	no	omitted → bind 127.0.0.1:0 (OS ephemeral port)	Loopback TCP port
--token T	no	omitted → random ({pid:x}{nanos:x})	Bearer token for /api/*

--ui probe order when the flag is omitted (serve::default_ui_dir):

1. clients/studio/dist
2. ../clients/studio/dist
3. ../../clients/studio/dist
4. <exe>/../../clients/studio/dist (three parents up from the binary)

Each candidate must contain index.html. If none match, the API still serves; static UI falls back to a small HTML placeholder (“build clients/studio or pass --ui”).

On start, stderr prints the listen URL with ?token=…, plus db, schema, and ui paths.

Exit

• 0: only if serve::run returns (it normally loops forever)
• 1: bad flags, bind/open/schema failure

Example

cargo run -p eelgrass-cli -- serve ./mydb examples/demo_schema.eel --port 8787

Full route reference: HTTP API.

---

studio

Same as serve, then opens the system browser to http://127.0.0.1:<port>/?token=<token> (xdg-open / open / cmd start).

Synopsis

cargo run -p eelgrass-cli -- studio <db_dir> <schemas.eel> \
  [--ui <dist>] [--port N] [--token T]

Args / flags

Identical to serve (--ui, --port, --token with the same defaults).

If no UI dist is found, stderr warns:

eelgrass studio: UI dist not found (build clients/studio or pass --ui <dist>)
continuing with placeholder page…

and the process still serves the API (plus placeholder HTML).

Example

# build UI once
npm --prefix clients/studio run build

cargo run -p eelgrass-cli -- studio ./mydb examples/demo_schema.eel \
  --ui clients/studio/dist

See Studio.

---

compact

Rewrite live rows for one tenant (v1 compact). Opens <db_dir>, optionally binds a non-default tenant, then calls db.compact().

Synopsis

cargo run -p eelgrass-cli -- compact <db_dir> [tenant]

Args

Arg	Required	Default	Description
<db_dir>	yes	—	Durable DB directory
[tenant]	no	default	Tenant name to compact

Behavior

On success, prints something like:

compacted tenant 'default': N collection(s), M row(s) rewritten in Tms

Exit

• 0: compact succeeded
• 1: cannot open DB, unknown tenant, or compact error

Examples

cargo run -p eelgrass-cli -- compact ./mydb
cargo run -p eelgrass-cli -- compact ./mydb acme

See also Health and compact and the HTTP compact op.