fracta debug

fracta debug is the entry point for diagnostic commands that inspect a running deployment. Unlike most CLI verbs it does not require a fracta project directory: every subcommand resolves its target from explicit flags or environment variables, so you can run it from anywhere.

Debugging and diagnostic commands.

Usage:
  fracta debug [command]

Available Commands:
  gateway     Inspect a running fracta-gateway pod's live state.
  registry    Manage the MCP server registry (debug/admin).

Command tree

fracta debug
├── gateway
│   └── policy        Fetch the gateway's tool-policy and visibility snapshot.
└── registry          (manage the MCP server registry — see existing notes in
                       reference/cli/registry.md; debug entry retained for
                       operator muscle memory)

`gateway policy`

Fetches the gateway’s tool-policy and visibility snapshot. This is the verification command for Gateway Tool Policy: after you edit a tool_policy block, gateway policy confirms the gateway loaded it and shows you exactly which tools are visible vs denied.

Usage:
  fracta debug gateway policy [flags]

Flags:
      --cp-url string        control-plane API URL (default: control_plane_api.url in fracta.yaml)
      --direct               skip the CP API and call the gateway directly
                             (requires cluster-internal DNS or port-forward)
      --gateway-url string   gateway base URL for --direct mode (default:
                             gateway.url in fracta.yaml or $FRACTA_GATEWAY_URL)
      --verbose              include per-tool visibility breakdown
      --json                 emit raw JSON instead of pretty-printed text

URL resolution

By default the request is routed through the control-plane API (which proxies to the gateway pod), so thin-client operators don’t need cluster-internal DNS or kubectl port-forward to the gateway Service. Resolution order:

--cp-url <url> / control_plane_api.url in fracta.yaml — preferred path; the CP daemon proxies to its configured gateway URL.
--direct flag — skip the CP API and hit the gateway directly.
--gateway-url <url> / $FRACTA_GATEWAY_URL / gateway.url in fracta.yaml — direct fallback.

When --direct --gateway-url is supplied, no project lookup happens — the command works from any directory. Without the explicit flag, it’ll best-effort walk up for a fracta project and read gateway.url if one is found.

Default output

Without --verbose, the command prints a summary of the gateway’s policy state:

$ fracta debug gateway policy --direct --gateway-url http://localhost:8080
Gateway: http://localhost:8080
Has registry store:   true
Has policies:         true
Visible set built:    true (generation 2)
Catalog size:         4
Visible:              2
Denied by policy:     2
Disabled by registry: 0

Policies (1 servers):
  fracta-test-server:
    deny:       (none)
    allow_only: [ping, echo]

Field meanings:

Field	Meaning
`Has registry store`	The gateway is wired up to a persistent registry (postgres/sqlite). Without one, `disabled_by_registry` always reports 0.
`Has policies`	At least one `tool_policy` block was loaded from config. False means policy is misconfigured or the pod hasn’t picked up a ConfigMap change.
`Visible set built`	The visibility pass completed at least once. `generation N` increments on every reload.
`Catalog size`	Total tools discovered across all configured MCP backends.
`Visible`	Tools agents will see in `tools/list`.
`Denied by policy`	Filtered out by `allow_only` / `deny` rules.
`Disabled by registry`	Turned off via `fracta config mcp tool disable`.

Visible + Denied by policy + Disabled by registry == Catalog size. If that identity doesn’t hold, the gateway is in an inconsistent state — file an issue.

`--verbose` per-tool breakdown

--verbose adds a per-tool listing with the reason each non-visible tool was filtered:

$ fracta debug gateway policy --direct --gateway-url http://localhost:8080 --verbose
... (header as above) ...

Tools:
  + fracta-test-server.echo
  - fracta-test-server.forbidden_action [denied_by_policy]
  + fracta-test-server.ping
  - fracta-test-server.restricted_action [denied_by_policy]

Tools are namespaced as <server>.<tool>. + is visible to agents; - is filtered out. The bracketed reason is either denied_by_policy or disabled_by_registry.

`--json`

Emits the raw response body for machine consumption — useful for assertions in shell scripts or CI:

$ fracta debug gateway policy --direct --gateway-url http://localhost:8080 --json --verbose \
  | jq '.tools | map(select(.visible == false)) | map(.namespaced_name)'
[
  "fracta-test-server.forbidden_action",
  "fracta-test-server.restricted_action"
]

From outside a fracta project

The most common use:

# From any directory, against a port-forwarded local gateway:
kubectl -n fracta port-forward svc/fracta-gateway 8080:8080 &
fracta debug gateway policy --direct --gateway-url http://localhost:8080 --verbose

# Or via $FRACTA_GATEWAY_URL:
export FRACTA_GATEWAY_URL=http://localhost:8080
fracta debug gateway policy --direct --verbose

No .fracta/ directory is required and no git init — --direct plus the URL is sufficient context.

`registry`

The registry subtree predates the debug group and retains its own page: see fracta registry for the full surface. The debug registry alias is kept for operator muscle memory.

What’s next

Gateway Tool Policy — the operator narrative for configuring and verifying policy.
fracta config mcp — adding backends and managing their policy declaratively.

Introduction

Getting Started

Swarm

Strategies

Patterns

Guides

Reference

Operations

Development

Contributing

Command tree

`gateway policy`

URL resolution

Default output

`--verbose` per-tool breakdown

`--json`

From outside a fracta project

`registry`

What’s next

​Command tree

​gateway policy

​URL resolution

​Default output

​--verbose per-tool breakdown

​--json

​From outside a fracta project

​registry

​What’s next

Command tree

`gateway policy`

URL resolution

Default output

`--verbose` per-tool breakdown

`--json`

From outside a fracta project

`registry`

What’s next