Reference

CLI.

`grid` is a single-binary command-line tool. It is a thin wrapper around the expression evaluator. Anything you type that isn't a recognized subcommand is parsed as a grid expression and executed.

The CLI does not invent verbs. The expression grammar is the same whether typed at a terminal, embedded in an attention cell, or used as a capability projection.

For the expression grammar itself, see Language. For encryption, see Encryption. For the sigil set used in expressions, see Sigils.

Invocation

grid -g <path> <expression>         # explicit grid file
grid <subcommand>                   # file-level operation
grid --help                         # usage
grid --version                      # version

A grid exists the moment you write a cell into it. There is no create command. If the file at the chosen path does not exist and your expression is a write, the file is created.

Options

Flag	Meaning
`-g <path>` / `--grid <path>`	Path to the `.grid` file
`-i <id>` / `--identity <id>`	Override `GRID_IDENTITY` for this invocation
`--body-file -`	Read cell body from stdin (for multi-line writes)
`--version` / `-V`	Print version
`--help` / `-h`	Show usage

Multi-line writes use --body-file -:

cat <<EOF | grid -g my.grid --body-file - "write @/notes/long type: note body: x"
First line of the note.
Second line.
Third line.
EOF

The body: x in the expression is a placeholder; --body-file - replaces it with the stdin content.

Identity

Every grid expression evaluates under exactly one identity. Resolution order:

-i <id> / --identity <id> flag
GRID_IDENTITY environment variable

If neither is set, identity defaults to unknown.

GRID_IDENTITY=alice grid -g my.grid "study: @/**"
grid -i alice -g my.grid "study: @/**"

There is no anonymous mode and no root mode. A grid with no @/system/identities/<name> subtree is permissive: every identity sees everything. The moment any identity cell exists, the grid becomes strict; an identity without a matching capability cell sees an empty grid.

Subcommands

Subcommands are file-level operations that do not compose with the expression grammar.

Inspection and integrity

Command	Effect
`status`	Format, cell count, sealed/locked state, genesis presence
`verify`	Walk the chain and verify SHA-256 integrity at every cell
`coordinate`	Print the grid's master coordinate (derives from genesis on demand)
`hash`	Print GHA-1024 of the genesis cell + master coordinate
`dump`	Export the grid as human-readable text
`migrate`	Rebuild grid; add genesis if missing

grid -g my.grid status
grid -g my.grid verify
grid -g my.grid coordinate
grid -g my.grid hash

Cell-level encryption (CLE)

Command	Effect
`lock`	Encrypt cell bodies whose sensitivity is above `public`
`unlock`	Decrypt CLE-encrypted bodies

Passphrase is read from GRID_PASSPHRASE if set; otherwise the CLI prompts. See Encryption for full details on key derivation and the keychain.

GRID_PASSPHRASE=secret grid -g my.grid lock
GRID_PASSPHRASE=secret grid -g my.grid unlock

Grid-level encryption (GLE)

Command	Effect
`seal`	Encrypt the entire file as one opaque blob
`unseal`	Decrypt a sealed grid back to its binary form

seal prints the grid's coordinate and a recovery code (the full genesis GHA hex). The keychain at ~/.grid/keychain.grid also records the recovery anchor automatically.

GRID_PASSPHRASE=secret grid -g my.grid seal
GRID_PASSPHRASE=secret grid -g my.grid unseal

Environment variables

Variable	Purpose	Default
`GRID_IDENTITY`	Identity for capability projection	`unknown`
`GRID_PASSPHRASE`	Passphrase for lock/unlock/seal/unseal	(prompt)

Expression sugar

The CLI recognizes a few convenience forms that expand to canonical expressions:

Sugar	Equivalent
`fetch @/path`	`study: @/path as: full`

These are parsed at the front end; the underlying execution is the same.

What the CLI does not have

There is no login command; identity is environmental or flag-set. There is no password; identity is asserted, and capability cells decide what that identity may see. There is no create; write a cell to a non-existent path and the file is created. There is no schema command; grids have invariants (themselves cells), not schemas. There is no admin subcommand; administration is writing capability cells. There is no --secure flag; security is the capability projection, not a CLI mode. There is no --watch flag; watch is a verb in the expression grammar.