GaiaFTCL CLI Reference — Swift M⁸¶

Every executable the cell ships is declared as a .executable product in cells/xcode/Package.swift. This page is the canonical list of those CLI members: what each one is, how it is invoked, the exact argument grammar, and the substrate subjects / receipts it touches.

Build any member from the cell root:

cd cells/xcode
swift build --product <Name>
.build/debug/<Name> [args]

Member index¶

Member	Role	Subcommands	Exit semantics
VQbitVM	vQbit virtual machine daemon	none (env-configured)	long-running
GaiaRTMGate	Requirements-traceability gate	none	0 = CALORIE
FranklinConsciousnessService	Franklin awakening service	none (mode flag)	long-running / one-shot
GaiaFTCLApp	macOS SwiftUI application	none (GUI)	long-running
S4DegradeInject	S⁴ degradation injector	none	0 = published
QuantumOQInjector	Quantum-domain OQ runner	`--test OQ-QM-001…007`	0 = CALORIE
XcodeSubstrateCLI	Sovereign build/test/sign wrapper	`build` `test` `sign` `reflect` `probe`	0 = CALORIE
FranklinBTCMiner	Bitcoin PoW nonce searcher	`mine` `moor` `verify` `bench` `pool` `close` …	0 = CALORIE
NonceArchaeology	Historical nonce structure analysis	none	0 = analyzed
GroverCircuit	Grover circuit state-vector measurement	none	0 = receipt sealed
VQbitGameCircuit	Exact-rational vQbit LVC game circuit	none	0 = CALORIE

Verdict tokens are uniform across the cell: CALORIE (cleared / cure), REFUSED (ran to the frontier without clearing, frontier named honestly), BLOCKED (bad input or execution error).

VQbitVM¶

The vQbit virtual machine. It accumulates S⁴ deltas per prim, fires the full M⁸ pipeline when a prim's four-axis mask saturates, runs the Bell/CHSH gate plus the constitutional invariants, and publishes the resulting C⁴ projection.

Source: Sources/VQbitVM/ · Form: .build/debug/VQbitVM (daemon, runs continuously)

Configuration is by environment, not flags:

GAIAFTCL_TENSOR_N — qualified manifold row count. Required; the VM exits 2 if unset.
GAIAFTCL_TENSOR_PATH — manifold tensor path (defaults via GaiaInstallPaths).
GAIAFTCL_OVERFLOW_MAP_PATH — overflow map URL (optional).
GAIAFTCL_VQBIT_POINTS_LOG — vQbit points log path (optional).

Subscribes: SubstrateWireSubjects.s4Delta, gaiaftcl.tau.sync.state, gaiaftcl.franklin.stage.moored, gaiaftcl.franklin.stage.unmoored. Publishes: SubstrateWireSubjects.c4Projection, gaiaftcl.vqbit.vm.ready, gaiaftcl.vqbit.vm.heartbeat.

GaiaRTMGate¶

Confirms the Requirements Traceability Matrix exists at the expected path and is valid JSON, then returns terminal state. Used as a qualification gate.

Source: Sources/GaiaRTMGate/

.build/debug/GaiaRTMGate [--repo-root=PATH]

--repo-root defaults to the current directory. Exit 0 = CALORIE, 1 = REFUSED.

FranklinConsciousnessService¶

Drives the Franklin consciousness actor. Either runs one preflight cycle and prints a JSON report, or awakens the actor continuously.

Source: Sources/FranklinConsciousnessService/

.build/debug/FranklinConsciousnessService --preflight-once   # one JSON report, then exit
.build/debug/FranklinConsciousnessService                    # continuous awakening loop

Delegates to FranklinConsciousnessActor.shared.

GaiaFTCLApp¶

The full macOS SwiftUI application — Franklin consciousness, language-game contracts, the M⁸ manifold renderer, and in-app IQ/OQ/PQ qualification. Enforces single-instance via an advisory lock at /tmp/franklin.sovereign.lock; closing a side window does not terminate the app.

Source: Sources/GaiaFTCLApp/

.build/debug/GaiaFTCLApp      # launches the macOS window

No CLI flags. Subscribes to substrate NATS subjects internally via FranklinDriver and LocalC4Subscriber.

S4DegradeInject¶

Publishes low S⁴ deltas (0.05 on all axes) for every active language_game_contracts row, to drive vQbit VM C⁴ projections.

Source: Sources/S4DegradeInject/

.build/debug/S4DegradeInject

Connects to NATS at 127.0.0.1:4222 and reads the substrate DB. Publishes: SubstrateWireSubjects.s4Delta. Exit 0 published · 2 NATS not connected · 3 no active contracts · 1 error.

QuantumOQInjector¶

Operational-qualification runner for the quantum-domain contracts. Injects S⁴ deltas, waits for the matching C⁴ projection, and validates the terminal state against the selected test spec.

Source: Sources/QuantumOQInjector/

Status probes (run and exit):

.build/debug/QuantumOQInjector --ping            # NATS + τ/mooring status
.build/debug/QuantumOQInjector --tau-status      # τ block height and source
.build/debug/QuantumOQInjector --mooring-status  # cell latitude/longitude/s3_spatial

Tests select with --test <ID>:

# OQ-QM-001 — terminal states at fixed s-mean values
.build/debug/QuantumOQInjector --test OQ-QM-001 --prim ProjectionProbe --s-mean 0.85 [--runs N] [--timeout SEC]

# OQ-QM-002 — monotonic c3_closure across a sequence; all terminal states observed
.build/debug/QuantumOQInjector --test OQ-QM-002 --prim CircuitFamily --s-mean-sequence 0.85,0.66,0.20,0.05

# OQ-QM-003 — S⁸ stability across a Franklin cycle
.build/debug/QuantumOQInjector --test OQ-QM-003 --prim VariationalFamily --inject s1=0.85,s2=0.66,s3=0.20,s4=0.05 [--wait-franklin-cycle]

# OQ-QM-004 — single projection at given s-mean
.build/debug/QuantumOQInjector --test OQ-QM-004 --prim LinearAlgebraFamily --s-mean 0.85

# OQ-QM-005 — c3_closure improvement post-cycle with receipt validation
.build/debug/QuantumOQInjector --test OQ-QM-005 --prim SimulationFamily --s-mean 0.85 [--wait-franklin-cycle]

# OQ-QM-006 — monotonic ascending c3_closure over a sequence
.build/debug/QuantumOQInjector --test OQ-QM-006 --prim BosonicFamily --s-mean-sequence 0.20,0.66,0.85

# OQ-QM-007 — algorithm-count sum, residual terminal check, closure_residual_max
.build/debug/QuantumOQInjector --test OQ-QM-007 --db /path/substrate.sqlite --log /path/vqbit.log

Predefined --prim roles: ProjectionProbe, CircuitFamily, VariationalFamily, LinearAlgebraFamily, SimulationFamily, BosonicFamily, ErrorCorrectionFamily, Tokamak (a raw game_id is also accepted).

Other flags: --runs N (default 1) · --timeout SEC (C⁴ wait, default 10) · --db PATH · --log PATH · --wait-franklin-cycle · --help/-h.

Subscribes: SubstrateWireSubjects.c4Projection, optionally gaiaftcl.franklin.monologue. Publishes: SubstrateWireSubjects.s4Delta. Exit 0 CALORIE · 2 REFUSED (assertion failed) · 1 BLOCKED.

XcodeSubstrateCLI¶

Sovereign wrapper for every Xcode build / test / sign operation. Routes each one through the constitutional gate and seals a receipt in franklin_xcode_receipts.

Source: Sources/XcodeSubstrateCLI/

.build/debug/XcodeSubstrateCLI build  [--scheme=NAME] [--config=debug|release] [--package-path=PATH]
.build/debug/XcodeSubstrateCLI test   [--filter=FILTER] [--expected=COUNT] [--package-path=PATH]
.build/debug/XcodeSubstrateCLI sign   --path=PATH [--identity=IDENTITY]
.build/debug/XcodeSubstrateCLI reflect [--package-path=PATH]
.build/debug/XcodeSubstrateCLI probe   [--package-path=PATH]

--config defaults to debug; --identity defaults to - (auto); --package-path is auto-discovered when omitted. Exit 0 CALORIE · 2 REFUSED (gate blocked) · 1 BLOCKED.

FranklinBTCMiner¶

Sovereign Bitcoin proof-of-work nonce searcher. Double-SHA256 grind dispatched through the substrate's vQbit invariant (or a forced classical path), reporting the substrate's measured rate; the verdict is whatever it produces.

Source: Sources/FranklinBTCMiner/

.build/debug/FranklinBTCMiner mine   --header=HEX160 (--target=HEX64 | --bits=N) [--threads=N] [--seconds=N] [--classical] [--netdiff=F]
.build/debug/FranklinBTCMiner moor   --header=HEX160 (--target=HEX64 | --bits=N) [--reader=ID] [--priority=...] [--threads=N] [--seconds=N] [--classical]
.build/debug/FranklinBTCMiner verify --header=HEX160 (--target=HEX64 | --bits=N)
.build/debug/FranklinBTCMiner bench  [--seconds=N] [--threads=N]
.build/debug/FranklinBTCMiner selftest [--bits=N] [--threads=N] [--seconds=N]
.build/debug/FranklinBTCMiner pool   --url=HOST:PORT (--worker=NAME | --wallets=a,b,…) [--password=...] [--netdiff=F] [--btcusd=F]
.build/debug/FranklinBTCMiner close  --header=HEX160 (--target=HEX64 | --bits=N) [--threads=N] [--seconds=N] [--wallet=ADDR] [--node-endpoint=URL] [--netdiff=F] [--classical]
.build/debug/FranklinBTCMiner bench-algos [--seconds=N] [--threads=N] [--header=HEX160]
.build/debug/FranklinBTCMiner schedule --miner-pid=PID [--threshold=F] [--poll=N]
.build/debug/FranklinBTCMiner reinvest --btc=AMOUNT --target=NAME [--usd=F] [--exchange=...] [--experiment=...] [--confirm]
.build/debug/FranklinBTCMiner bridge
.build/debug/FranklinBTCMiner stratum-selftest

Subcommand intents: mine solo grind against a target · moor measurement mode (registers the game, no broadcast, internal CALORIE on first clear) · verify check a header against target · bench pure throughput · selftest grind against N leading zero bits · pool Stratum v1 with wallet rotation · close one-gate closure (grind + eight-axis verdict) · bench-algos benchmark every algorithm · schedule background monitor of a miner PID · reinvest record a reinvestment link (no money moves; dry-run unless --confirm) · bridge render the funding bridge · stratum-selftest exercise the Stratum v1 protocol.

Key flags: --header=HEX160 (80-byte header, 160 hex chars) · --target=HEX64 or --bits=N (one required for the grinding subcommands) · --threads=N (default = core count) · --seconds=N (time budget) · --classical (force classical SHA256d) · --reader=ID (default operator-wallet-Rick-only) · --priority=citizen-background|userInitiated.

Wallet addresses are never generated by this tool. Pool wallets come from --wallets; closure reporting takes --wallet=ADDR. Authoritative addresses are produced only by substrate-resident wallet operations.

Receipts: private receipts sealed to btc_mining_receipts/<UTC>.json; game definition moored to discovery_game_definitions/btc_mining_loop.json. Exit 0 CALORIE · 2 REFUSED (deadline reached, frontier named) · 1 BLOCKED.

NonceArchaeology¶

Fetches real historical mainnet block headers and winning nonces, then runs uniformity (χ²) and correlation (Pearson r) tests looking for exploitable structure. Fetches are cached so a range is pulled once.

Source: Sources/NonceArchaeology/

.build/debug/NonceArchaeology --from=0 --to=2000        # analyze a height range
.build/debug/NonceArchaeology --tip --count=2000        # analyze recent blocks from the tip
.build/debug/NonceArchaeology --from=0 --to=200 --verify # reconstruct headers, prove the data is real

--from (default 0) · --to (default 2000) · --tip · --count=N (with --tip, default 2000) · --verify. Cache at nonce_archaeology/cache/blocks_<lo>_<hi>.json. Exit 0 analyzed · 1 no blocks fetched / network error.

GroverCircuit¶

Exact state-vector measurement of the BTC-mining Grover circuit. Measures τ (wall-clock per iteration), runs it head-to-head against brute force, and seals a private receipt with the measured τ and the honest scaling to 2⁵⁹ iterations.

Source: Sources/GroverCircuit/

.build/debug/GroverCircuit --qubits=16
.build/debug/GroverCircuit --qubits=16 --header=<HEX> --zerobits=K

--qubits=N register size 4–28, default 16 (state vector = 2ᴺ amplitudes) · --header=HEX (default 0xa7 × 76 bytes) · --zerobits=K target difficulty in leading zero bits (default = qubits ≈ one marked state). Receipt: btc_mining_receipts/GROVER-<timestamp>.json. Exit 0 (receipt sealed).

VQbitGameCircuit¶

The vQbit LVC game circuit in exact rationals — no Float. N=4 instance: Hadamard init, phase oracle, diffusion, vQbit measurement, the eight-axis verdict, and a falsifier check on the exact-Rat algebra.

Source: Sources/VQbitGameCircuit/

.build/debug/VQbitGameCircuit       # N=4 fixed instance

Prints the state vector at each gate, the measurement, and the eight-axis verdict (Trust, Identity, Closure, Consequence, Fidelity, Transfer, Completeness, Frontier-honesty). Closure requires the final state to equal |11⟩ exactly (GTWED distance 0); Frontier-honesty seals the result at the N=4 instance only — no general-N or hardware-advantage claim. Exit 0 CALORIE (all axes pass, falsifier intact) · 1 REFUSED.

Adding a new CLI member¶

A new executable becomes a documented CLI member in three steps:

Add Sources/<Name>/main.swift (or an @main entry point) under cells/xcode/Sources/.
Declare it as .executable(name: "<Name>", targets: ["<Name>"]) plus a matching .executableTarget in Package.swift.
Add a section to this page following the same shape: source path, invocation grammar in a fenced block, flags, substrate subjects / receipts, and exit semantics — then add the row to the member index.

Federation cosignature: pending

This page is not yet in the signed manifest. Run gaiaftcl wiki sign --all.