Inspect a local debug runtime

The FaultAtlas command-line interface (CLI) reads an explicit local debug runtime. It does not connect to production telemetry or discover application state automatically.

Read registered state

Create a client configured once, then complete a handshake before requesting a snapshot. The client owns the session, so protected calls need no token arguments.

import { createDebugClient, nodeFetchTransport } from "@faultatlas/cli";

const client = createDebugClient({
  host: "127.0.0.1",
  port: 4317,
  timeoutMs: 2_000,
  transport: nodeFetchTransport,
});
await client.handshake();
const cart = await client.snapshot("cart");
const itemCount =
  typeof cart === "object" &&
  cart !== null &&
  "itemCount" in cart &&
  typeof cart.itemCount === "number"
    ? cart.itemCount
    : 0;
console.info("Cart snapshot received", { itemCount });

Complete the operator loop

faultatlas state cart --path itemCount,items.0.sku --json
faultatlas events --wait '{"payload":{"type":"cart.updated"}}' --timeout 5000 --json
faultatlas doctor --json
faultatlas capture --output ./faultatlas-capture.json

Event wait checks bounded recent events newest-first before following the live stream. Capture writes a bounded, redacted local artifact; targeted capture remains available with capture --client CLIENT_ID.

Choose the right command

• Use state for one explicitly registered snapshot.
• Use events --wait when a local action should produce a known event.
• Use doctor to check handshake, capabilities, registration, and transport together.
• Use capture when another developer needs a bounded diagnostic artifact.

Matcher size, depth, key count, event-line size, wait time, and output size are bounded. Existing output files are never overwritten.

Troubleshooting

Run doctor first. If handshake fails, confirm the host and port and restart the local debug host. If state is missing, register that exact state name in the application; the CLI intentionally cannot discover it. If an action is denied, review the exact development allowlist rather than widening it with a prefix.

Keep the transport on loopback and register every readable state key in the debug runtime. The CLI does not provide automatic discovery, DOM/session capture, bus emit, or remote/production live-debug.