CLI reference

Status: developer workbench. The gestalt CLI is a vessel that crosses the membrane the same way a browser, an MCP tool, or a native app does. Source: crates/gestalt-cli/src/main.rs.

The CLI is a workbench, not an admin app. It exists to let developers and operators inspect crossings, run scenarios, and exercise the membrane discipline directly. See concepts: the membrane and meditation 010 for the principles behind it.

Build

The CLI is built from the workspace:

cargo build -p gestalt-cli
# binary at target/debug/gestalt

Or run directly:

cargo run -p gestalt-cli -- --help

Throughout this page, gestalt means cargo run -p gestalt-cli -- unless you have built and aliased the binary.

Top-level commands

gestalt demo            full-scenario demos (company-home, company-simulation)
gestalt action-flow     execute action flows (issue-invoice, sovereign-invoice)
gestalt scan            inspect serious-button-shaped acts
gestalt cloud           cloud membrane operations (provision, signup, contract, serve)
gestalt workbench       workbench surface inspection (policy, sandbox, mcp, macos)
gestalt adapter         adapter inspection (intake fixtures, review, ai-ocr policy)
gestalt human-auth      human-auth contracts and fixtures
gestalt deploy          deploy planning (plan-fixture)
gestalt security        security artifacts (threat-model, key-custody, red-team)
gestalt proof           proof disclosure policy and fixtures
gestalt ops             ops surface (observability, status, refusal explorer)
gestalt scenario        worked scenarios (march-close, sovereign-pendulum, france-expansion)
gestalt authority       authority topology (substrate-map, resolve-context, package-catalog, source refresh, stress)
gestalt surreal         SurrealDB-related operations

Run gestalt <command> --help for any group’s subcommands.

Scenarios — the easiest way to see Gestalt work

Scenarios run a complete fixture flow end-to-end and print every crossing.

`gestalt scenario march-close`

The flagship workbench scenario. Walks:

Initialize a local fixture substrate.
Publish bootstrap capability and fixture domain capabilities.
Create a provisional CompanyGeist.
Add identity + registry evidence.
Claim and grant standing for Anna as Geschäftsführerin.
Issue an invoice atom in record reality.
Watch receivable + VAT + evidence + period-close closure surfaces open.
Ingest a bank movement that does not match.
Request period close → Gravity refuses (economic_closure_surface_open).
Admit a financial_period_non_closure tension.
Emit effects (require evidence, open review matter, block clean close).
Ask gestalt zeit why for the block.
Fork a projected reality.
Admit candidate evidence inside the projection.
Attempt promotion.
Promote if Gravity re-evaluates successfully against record; discard otherwise.

gestalt scenario march-close

`gestalt scenario sovereign-pendulum`

Demonstrates how a sovereign Pendulum emission (e.g. a regulator notice) changes admissibility for future atoms.

`gestalt scenario france-expansion`

The France market-entry projection scenario described in concepts: realities.

Cloud commands

`gestalt cloud serve-fixture --addr 127.0.0.1:3011`

Start the fixture cloud locally. The membrane is at the bound address. See getting-started.md and operations/local-fixture.md.

gestalt cloud serve-fixture --addr 127.0.0.1:3011 --max-requests 1000

--max-requests bounds the number of requests before the server exits (useful for CI smoke tests).

`gestalt cloud membrane-contract`

Print the embedded membrane contract.

gestalt cloud membrane-contract

`gestalt cloud selftest-routes`

Self-test the fixture HTTP routes without binding a socket. Useful for CI.

gestalt cloud selftest-routes

`gestalt cloud rehearse-membrane`

Run a comprehensive membrane rehearsal that exercises the contract end-to-end.

`gestalt cloud provision-fixture-company` and `signup-fixture`

Seed the fixture company and create a fixture signup. Used by other demos.

Action flows

`gestalt action-flow issue-invoice [--fixture]`

Run the invoice-issue action flow as a fixture.

`gestalt action-flow sovereign-invoice [--fixture]`

Run the sovereign-invoice action flow as a fixture.

Scan

`gestalt scan serious-button [--fixture]`

Inspect a serious-button-shaped act and what its membrane crossing would entail.

Workbench

`gestalt workbench policy`

Print the agent / workbench permission contract (the open SDK boundary, closed runtime boundary, forbidden surface).

`gestalt workbench sandbox-policy`

Print the Koerper sandbox policy.

`gestalt workbench mcp-manifest`

Print the MCP server manifest.

`gestalt workbench macos-manifest`

Print the macOS workbench manifest.

Adapters

`gestalt adapter intake-fixtures`

Run intake fixtures across the supported adapters (DATEV, Lexware, Bilanz, geocode, XRechnung, ZUGFeRD, bank, Stripe).

`gestalt adapter review-fixtures`

Run the adapter review fixture.

`gestalt adapter ai-ocr-geospatial-policy`

Print the AI-OCR / geospatial intake policy.

Human auth

`gestalt human-auth contract`

Print the HumanAuth contract.

`gestalt human-auth private-session-fixture --subject ... --scopes ...`

Run a private-passkey fixture session.

`gestalt human-auth cpu-face-match-fixture --scenario ...`

Run a CPU face-match fixture for one of the known scenarios.

Deploy

`gestalt deploy plan-fixture`

Print the fixture deployment plan. The actual deploy lives in deploy/hetzner-cloudflare/ — see operations/hetzner-cloudflare.md.

Security

gestalt security threat-model
gestalt security key-custody
gestalt security red-team-matrix

Print the corresponding security contracts.

Proof

gestalt proof disclosure-policy
gestalt proof disclosure-fixture

Ops

gestalt ops observability     print the observability contract
gestalt ops status-fixture    show fixture runtime status
gestalt ops refusal-explorer  inspect the refusal taxonomy

Authority

`gestalt authority substrate-map`

Print the authority substrate map.

`gestalt authority resolve-context --from DE --to FR --tag warehouse_country:FR --evidence ...`

Resolve an authority context against the membrane. Same as the SDK resolveAuthorityContext call.

`gestalt authority package-catalog`

Print the embedded authority package catalog.

`gestalt authority resolve-evidence-fixture` / `source-refresh-fixture`

Run authority evidence and source-refresh fixtures.

`gestalt authority stress-resolver`

Stress-test the authority resolver.

Surreal

gestalt surreal ...

SurrealDB-related operations (schema apply, migrations, etc.). Per workflow 018 finding 2, durable Surreal profile is in progress.

Patterns and idioms

Always inspect outcomes, not exit codes

The CLI is a workbench. A refusal from the membrane is not a command failure. It is a structured finding. The CLI prints the refusal shape and exits 0; an outright command failure (bad args, network problem) exits non-zero.

Receipts everywhere

Most commands print receipt:... refs aggressively. The receipt is the thing you can verify later, not the human-readable summary.

Same command, different signing posture

The same action-flow issue-invoice can produce a committed atom (dev signing) or a pending action (proposal-only mode). The underlying membrane crossing is the same; the vessel’s signing posture decides the outcome.

`--fixture` flag

Many subcommands take --fixture to confirm fixture mode is intentional. This flag exists so a future production posture cannot silently accept a fixture call.

What the CLI is not

Not a database client. It does not connect directly to SurrealDB.
Not an admin app. It does not bypass Gravity. It crosses the membrane.
Not a backdoor. Even in dev, the CLI’s signing posture is declared.

Where to read next

Getting started
Operations: local fixture
Concepts: the membrane
Meditation 010: workbench, vessel, membrane

CLI reference

Build

Top-level commands

Scenarios — the easiest way to see Gestalt work

gestalt scenario march-close

gestalt scenario sovereign-pendulum

gestalt scenario france-expansion

Cloud commands

gestalt cloud serve-fixture --addr 127.0.0.1:3011

gestalt cloud membrane-contract

gestalt cloud selftest-routes

gestalt cloud rehearse-membrane

gestalt cloud provision-fixture-company and signup-fixture

Action flows

gestalt action-flow issue-invoice [--fixture]

gestalt action-flow sovereign-invoice [--fixture]