GG CLI Reference

Parent README: ../README.md

Use this as the command map for GG developers. Prefer package scripts and repo-owned wrappers from the monorepo root.

First Commands

GNODE_FORCE_TSX=1 pnpm --dir open-source/gnosis run monster:echo
GNODE_FORCE_TSX=1 pnpm --dir open-source/gnosis run monster:fib20

These are the smallest advertised smoke tests. They prove the checkout can run checked-in fixtures through the Gnosis execution path. The GNODE_FORCE_TSX=1 prefix is intentional for first-run docs: it bypasses stale prewarmed bundle state and uses the live TypeScript bridge.

Command Surfaces

Common Workflows

Author Direct GG

node open-source/gnosis/bin/gnosis.js lint open-source/gnosis/example.gg --target node
node open-source/gnosis/bin/gnosis.js analyze open-source/gnosis/betti.gg --json
node open-source/gnosis/bin/gnosis.js run open-source/gnosis/example.gg

Use direct node open-source/gnosis/bin/gnosis.js only when the package script does not expose the exact local workflow. For repeatable workspace tasks, prefer pnpm --dir open-source/gnosis run ... or pnpm run a0 -- run <target>.

Run TypeScript Through Gnosis

pnpm --dir open-source/gnosis run gnode -- run ./path/to/app.ts
pnpm --dir open-source/gnosis run gnode -- compile ./path/to/app.ts
pnpm --dir open-source/gnosis run gnode -- schedule ./path/to/app.ts --lanes 4 --strategy cannon

The TypeScript bridge supports topology-friendly orchestration entrypoints and fails closed on unsupported statements. See ../gnode/README.md.

Execute With Monster

GNODE_FORCE_TSX=1 pnpm --dir open-source/gnosis run monster:echo
GNODE_FORCE_TSX=1 pnpm --dir open-source/gnosis run monster:fib20

Lower-level native examples from the polyglot README:

cargo build --release --bin monster
./target/release/monster path/to/file.ts --export myFn --input-json '{"x":1}'
./target/release/monster path/to/file.ts --export myFn --resident-flow-stdio

Use the package scripts first. Use direct native binaries for runtime work, benchmarks, or local debugging.

Test GG

Use Gnosis-owned test adapters:

pnpm run a0 -- run @a0n/gnosis:test
pnpm --dir open-source/gnosis run test:quality-surface

For .test.gg authoring and runner behavior, use:

• ../src/testing/README.md
• ../examples/README.md
• Book 189

Validate Formal Or Capability Surfaces

pnpm run a0 -- run @a0n/gnosis:validate:ledger-mcp
pnpm run a0 -- run @a0n/gnosis:validate:mechanization-release-gate
pnpm run a0 -- run @a0n/gnosis:validate:lean-minimal
pnpm run a0 -- run @a0n/gnosis:validate:math-sandbox

Run the narrow target that matches the docs or code you changed. Do not widen to full workspace quality unless the blast radius requires it.

analyze Versus Executable Paths

analyze is report-only. It can explain topology shape, complexity, capabilities, or law/admission state, but it is not itself the admission gate.

Executable paths must fail closed when universe admission rejects the compiled topology:

• build
• run
• native
• test
• gnode
• module assembly
• immediate polyglot execution

Output Formats

Prefer machine-readable output when a command feeds another tool:

node open-source/gnosis/bin/gnosis.js analyze open-source/gnosis/betti.gg --json

Use human-readable output for local diagnosis and docs examples.

Environment Flags

Common flags documented by owning surfaces:

Sovereign Workflow Notes

• Use pnpm run a0 -- run <target> for workspace targets.
• Use pnpm --dir open-source/gnosis run <script> for package scripts.
• Do not document raw nx, raw deploy commands, or direct package installs as the normal path.
• For docs-only edits, run narrow docs/path checks plus any command examples you touched.