> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gloo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Commands

> Browse the typed command catalog and audit free-form exec invocations from the Foundry.

Last updated 2026-11-11

·
applies to 2026-09-03

·
main

The **Commands** page under Platform is the operator surface for the catalog of typed commands available to agents. Tier 1 catalog commands are typed, validated, and run under declared network policies. Tier 3 free-form commands issued through `sandbox_action` are tracked separately in the audit dashboard.

![Commands (light)](https://mintcdn.com/gloo-b243725a/xyq5perq6SLByPBn/forge/images/console/platform/commands-light.png?fit=max\&auto=format\&n=xyq5perq6SLByPBn\&q=85\&s=b240d05a11e6ddebaf04282dcd549ec3)

Commands — Forge Console at `/platform/commands`

## What you can do

* Browse and filter the typed command catalog on the **Catalog** tab, and open a command's detail page.
* Read a command's arguments, examples, recent invocations, granting skills and governance decisions on its detail page.
* Review recent Tier 3 free-form invocations and promotion candidates on the **Audit** tab.
* From a run or an artifact, trace which command ran and how governance decided it.

## Catalog index — `/platform/commands`

The page is split across two tabs at the top of the surface: **Catalog** (default, `/platform/commands`) and **Audit** (`/platform/commands/audit`).

The Catalog tab is a browse-and-filter view. Five aggregate stats sit above the filter bar; the grid below renders one card per row in `commandDefinitions`.

### Stat row

Each stat is a live count over the loaded catalog page (the v1 query fetches the first 50 rows):

| Stat | What it counts |
| - | - |
| Total Commands | Every row returned by the query |
| Read-Only | `riskClass === "read-only"` — typed commands that never mutate state |
| Mutates-FS | `riskClass === "mutates-fs"` — typed commands that touch the workspace filesystem |
| Network-Egress | `riskClass === "network-egress"` — typed commands permitted egress to declared hosts |
| Destructive | `riskClass === "destructive"` — typed commands that delete or destroy state |

The Privileged class exists in the schema (`riskClass === "privileged"`) but does not have its own stat tile — operators reach it through the risk filter when needed.

### Filters

Three filter axes compose AND-style. All filtering is in-memory across the loaded page; the underlying query supports server-side `source` / `riskClass` filters, but the v1 page applies them client-side so the stat row stays consistent with the filtered grid.

| Control | Scope | Values |
| - | - | - |
| **Search** | Substring match over `commandId`, `description`, and `tags[]` | Any string; case-insensitive |
| **Source pills** | `source` | All Sources · Builtin · Workspace · Marketplace |
| **Risk pills** | `riskClass` | All Risk · Read-Only · Mutates-FS · Network-Egress · Destructive · Privileged |

Cards in the grid are sorted alphabetically by `commandId`. A card/list view toggle sits beside the filter bar and persists through the `?view=` query param (`card` is the default).

### The command card

Each card is a fixed-shape summary of one row in `commandDefinitions`:

| Region | What it shows |
| - | - |
| Title | `commandId` (monospace) — stable identifier the agent uses to invoke |
| Sub-title | Catalog `version` (semver) |
| Top-right chip | Risk class — color-coded per the table below |
| Body | `description` — first 1–2 lines |
| Footer-left | Source chip (Builtin / Workspace / Marketplace) |
| Footer-left | Network policy chip (deny-all / allow-list / allow-all) — hover for the host list when allow-list |
| Footer-left | Idempotent badge (when `idempotent === true`) |
| Footer-right | Up to 3 tag chips |

#### Risk-class palette

The palette is shared with the run-view command-class breakdown widget so the same color always means the same risk class:

| Risk class | Color | Semantics |
| - | - | - |
| Read-Only | Green | No state mutation; safe to retry |
| Mutates-FS | Amber | Writes the workspace filesystem; idempotent if `idempotent === true` |
| Network-Egress | Blue | Permitted egress to declared hosts via `networkPolicy.allowedHosts` |
| Destructive | Red | Deletes or destroys state; requires explicit grant |
| Privileged | Purple | Privileged execution path; used for special-cased commands |

#### Network policy chip

| Mode | Meaning |
| - | - |
| `deny-all` | No egress permitted; sandbox network policy locked closed for the duration |
| `allow-list (N)` | Egress permitted only to the N declared hosts (suffix match); hover the chip for the host list |
| `allow-all` | Unrestricted egress; reserved for explicitly-opted-in commands |

Click any card to open the per-command detail page at `/platform/commands/[commandId]` (covered below).

## Detail page — `/platform/commands/[commandId]`

Each catalog command has a tabbed detail page reachable by clicking a card on the index. An unknown command id renders a "Command not found" empty state with a link back to the index.

| Tab | Content |
| - | - |
| **Overview** | Network policy (mode + allowed hosts when `allow-list`), risk class, source, version, idempotent flag, authored-by + workspace (when applicable), tags, timestamps. |
| **Args Schema** | Top-level fields parsed from `argsSchema` rendered as a property table (`field`, `type`, `required` / `optional`), with the full value under a collapsible **Raw schema**. A command with no arguments says so; a schema that cannot be parsed shows a notice above the raw value. When the catalog row stores only a source hash instead of a schema, the tab shows a notice that the schema preview is not yet stored, plus that hash, and no table or raw value. |
| **Examples** | The command's `meta.examples` list rendered as `{ intent, args }` cards. The `args` JSON is pretty-printed for copy-paste. |
| **Recent Invocations** | Sortable table of the command's last 50 invocations. Columns: started, agent, status, duration, target. Clicking a row navigates to the originating workflow run (`/production/workflows/convex/[runId]`) or factory (`/production/factories/[factoryId]`) when present. |
| **Grants** | Skills that grant this command. Each row shows the skill name, source chip, status, skill id, and grant date; clicking the row deep-links to `/platform/skills/[skillId]`. Empty state when no skill grants the command (typical for newly authored catalog entries before a skill is updated). |
| **Audit** | Recent governance decisions for this command. Each row shows the disposition (`pass` / `block` / `hold`), severity, decision reason, and links to the originating workflow run, step, and agent. Tier 1 only — Tier 3 free-form-exec rows are surfaced separately on `/platform/commands/audit`. |

The page is URL-driven via `?tab=` so deep links to a specific tab survive a refresh.

## Audit dashboard

The **Audit** tab (`/platform/commands/audit`) surfaces Tier 3 free-form `sandbox_action` command decisions captured by Trust Fabric, alongside promotion candidates derived from repeated command hashes. Tier 3 invocations are intentionally untyped; operators can promote stable, low-risk patterns to typed Tier 1 catalog commands.

Two sections stack in the dashboard:

1. **Recent Tier 3 invocations** — a table of every Tier 3 invocation in the active time window, showing the timestamp, agent, run/step ids, command-string hash prefix, inferred risk class, inferer confidence, and disposition (`pass` / `block` / `held`). A chip row at the top of the page selects the window: **1h** / **24h** / **7d** (default) / **30d**.
2. **Promotion candidates** — a card list of high-frequency, low-risk patterns suitable for catalog promotion. The platform flags any `commandStringHash` with **≥5** invocations in the active window AND inferred risk class in `{read-only, mutates-fs}`. Each card carries the hash prefix, the most-recent **sample command string** (best-effort — falls back to "Sample command unavailable" when the join can't resolve), count, last-seen relative time, inferred risk class chip, and an **Open issue** button that opens a pre-filled GitHub issue with the pattern signature **and the sample command** embedded — operators triage candidates from there into typed Tier 1 catalog commands.

Both surfaces are read-only — promotion is intentionally a deliberate human authoring step, not a one-click action. The button opens a pre-filled GitHub issue so the work is tracked and reviewed.

The audit dashboard depends on the structured fields populated on each governance audit entry (`commandTier`, `inferredRiskClass`, `inferenceConfidence`, `commandStringHash`, `disposition`). Auth: queries gate on the `audit:read` permission.

## Run-view command-class breakdown

When you open a workflow run under Production, the inspector surfaces a one-line readout of the run's command activity. The strip sits above the inspector tab navigation and shows:

* **Per-class invocation counts** — grouped by `inferredRiskClass` (read-only, mutates-fs, network-egress, destructive, privileged). Only Tier 3 free-form `sandbox_action` commands contribute: they carry the class inferred at invocation time. Tier 1 catalog rows are typed declaratively and write no `inferredRiskClass`, so they appear in the tier counts but in no risk-class bucket.
* **Governance disposition counts** — `allowed`, `blocked`, and `held` pulled from the run's governance audit log. `held` invocations are the held commands listed in [Approvals](https://docs.gloo.com/forge/console/production/approvals.md).

The strip self-hides on runs that didn't invoke any commands, so legacy or chat-only runs see no change. The strip is a readout; it does not filter the Tools tab.

## Artifact provenance

When you preview a file artifact on a workflow run view, a **Provenance** panel renders below the preview answering "which command invocation produced this file?" The panel picks the most recent invocation on the same run step that completed before the file was created.

| Tier | Render |
| - | - |
| **Tier 1** (catalog command) | Shows the command id, args summary, status, started-at, and duration. The "View command" CTA deep-links to `/platform/commands/[commandId]?tab=recent-invocations&invocation=<invocationId>` — the detail page auto-switches to the Recent Invocations tab and visually highlights the matching row. |
| **Tier 3** (free-form `sandbox_action`) | Shows "Produced by free-form exec" with a "View in audit" CTA that links to `/platform/commands/audit`. The audit dashboard does not currently support a `?hash=` deep link so the link lands on the dashboard root. |
| **Legacy** (pre-Phase-5 row or non-sandbox tool call) | Falls back to the tool id with a "View tool" CTA to `/platform/tools/[toolId]` when the row carries a tool definition id. |

The panel self-hides when no producing invocation can be resolved (legacy artifacts, parallel-tool-call ambiguity per Open Question #4 in the plan).

When a deep link lands on the detail page but the targeted invocation is older than the last 50 fetched rows, an inline notice surfaces above the table so operators know the link landed but the row is outside the visible window.

## Strict mode

Strict enforcement is the only mode; there is no audit-only mode:

* **Tier 3 commands inferred as `privileged` require an active exec grant** for the dispatching worker. Without an active grant the per-command policy blocks the call (`disposition: "block"`, `decisionReason: "privileged_unauthorized"`). Lower-risk Tier 3 classes are unaffected: `read-only` auto-allows, `mutates-fs` / `network-egress` allow or hold on the agent's rung (only `bounded` auto-allows, and `network-egress` also needs an allow-list network policy), and `destructive` always holds.
* **Granted workers** run the privileged command normally; the audit row records `decisionReason: "exec_grant_active"`, and the reason given when the grant was issued stays on the grant.
* **Tier 1 catalog commands** evaluate against their declared `riskClass` and the agent's rung.
* **Held Tier 1 commands** flow through [Approvals](https://docs.gloo.com/forge/console/production/approvals.md): everyone on the hold's approver list sees it under **Waiting on me**, and the first decision wins.

### Issuing a grant

The Console and the Forge API have no control for issuing or revoking a grant. Ask a platform
administrator to issue one. A grant names one worker and carries a required reason, recorded with the
grant, and an optional expiry for a time-boxed grant. The person who issues it is recorded as its
granter. Issuing or revoking a grant needs the **Approve approvals** permission (`approvals:approve`)
at the scope the request names: the worker's organization unit, or the platform when none is named.

Revoking a grant keeps it on record with who revoked it, when and why; a revoked grant cannot be
revoked again. A grant also stops applying once its expiry passes.

## Key state to watch

* **Promotion candidates** on the Audit tab — a free-form command pattern that recurs at low risk is a candidate for a typed catalog command.
* **Held and blocked dispositions** on the Audit tab and on a run's command-class strip — a held command waits in [Approvals](https://docs.gloo.com/forge/console/production/approvals.md); a blocked `privileged` command means the worker has no active grant.
* **Active grants** — each grant lets one worker run privileged free-form commands until it expires or is revoked.

## Related surfaces

* [Approvals](https://docs.gloo.com/forge/console/production/approvals.md) — where held commands are decided.
* [Tools](https://docs.gloo.com/forge/console/platform/tools) — the tool catalog, a related but distinct surface that lists registered `TOOL_SETS` entries.
* [Skills](https://docs.gloo.com/forge/console/platform/skills) — the skills that grant catalog commands.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.