Debug

Developer tooling for inspecting a running entity and the connections between entities. The debug group is hidden from the default grid --help output to keep the everyday surface small; it still shows under grid debug --help and grid --help all.

These commands act on live entities on the grid. Most take an entity address — a slug for an entity in your active grid, or a fully-qualified org:<org>/<entity> address for one elsewhere.

`grid debug call`

Send a test request from one entity to another and print the response. This exercises the same app-to-app path your code uses — the call carries the source entity’s identity and is subject to the callee’s caller grants — so it is the fastest way to confirm a calls:/callers: relationship works before wiring it into code.

grid debug call <to-entity> <path> [flags]

<to-entity> is the target address (for example billing-api or org:atomic/billing-api). <path> is the HTTP path on the target (for example /api/health).

Flag	Description
`--from <addr>`	Caller entity address. Defaults to the entity linked in the current folder (`.cloudgrid/link.json`).
`-X, --method <method>`	HTTP method (default `GET`).
`-d, --data <body>`	Request body, sent as-is.
`-H, --header <header...>`	Additional request headers, `Key: Value`. Repeatable.
`--verbose`	Show the grant state, decoded identity claims, and full headers.
`--json`	Machine-readable JSON output.

# From the entity linked in this folder, GET a route on another entity
grid debug call billing-api /api/health

# POST a body as a specific source entity
grid debug call org:atomic/billing-api /charges \
  --from org:atomic/checkout \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"amount": 500}'

# See why a call is allowed or denied
grid debug call billing-api /api/health --verbose

If the callee has not granted the caller, the request is rejected — check the callers: block on the target and see Wiring and bindings.

`grid debug ssh`

Open an interactive shell in a running pod for an entity named by slug, without local kubectl. This is the non-cwd counterpart to the folder-rooted shell — pass any entity in your active grid rather than the one linked in the current directory.

grid debug ssh <entity> [flags]

<entity> is the entity slug or id to shell into.

Flag	Description
`--service <name>`	Service to shell into. Defaults to the first running pod.

# Shell into an entity by slug
grid debug ssh billing-api

# Target a specific service when the entity runs more than one
grid debug ssh billing-api --service worker

The shell runs inside the live container, so anything you install or change is lost on the next deploy or restart. Use it to inspect the running environment — env vars, mounted paths, reachability — not to make persistent changes.