# Agentseam CLI

The agentseam command and every subcommand, generated from its argument parser.

The site generates this page at build time from the argparse parser of the installed agentseam.

> Ask the user before running any command on this page: each one changes how their agent or repository behaves.

## Every command and subcommand

Each command has its own section, from agentseam's own parser at the pinned commit. It writes arguments as argparse prints them and leaves out the `-h, --help` option.

| Command | Summary |
| --- | --- |
| `agentseam` | Agentseam CLI: inspect the matrix, wire hooks, audit a machine. |
| `agentseam agents` | List known agents |
| `agentseam matrix` | What each agent can enforce, per event |
| `agentseam tier-table` | The enforcement table, derived from the matrix |
| `agentseam doctor` | What is wired here; flag stale capability claims |
| `agentseam probe` | Measure what an agent's hooks actually enforce, against a driver |
| `agentseam probe list` | The trials and what each measures |
| `agentseam probe run` | Run trials against --driver; a table, or --report for submission |
| `agentseam probe conformance` | Compare the recorded agents; exit non-zero on a seam gap |
| `agentseam install` | Wire a handler command into an agent's config |
| `agentseam instructions` | Write standing instructions to every agent's file |
| `agentseam permissions` | Each agent's permission surface; render a policy into it |
| `agentseam packaging` | Where each agent looks for skills, subagents and commands |
| `agentseam uninstall` | Remove only agentseam's entries |

## `agentseam`

Agentseam CLI: inspect the matrix, wire hooks, audit a machine.

Usage:

```text
agentseam [-h] [--version]
          {agents,matrix,tier-table,doctor,probe,install,instructions,permissions,packaging,uninstall}
          ...
```

| Argument | Help |
| --- | --- |
| `--version` | Show program's version number and exit |

Subcommands:

- `agentseam agents`
- `agentseam matrix`
- `agentseam tier-table`
- `agentseam doctor`
- `agentseam probe`
- `agentseam install`
- `agentseam instructions`
- `agentseam permissions`
- `agentseam packaging`
- `agentseam uninstall`

## `agentseam agents`

List known agents

Usage:

```text
agentseam agents [-h]
```

No arguments besides `-h, --help`.

## `agentseam matrix`

What each agent can enforce, per event

Usage:

```text
agentseam matrix [-h] [--json] [--evidence]
```

| Argument | Help |
| --- | --- |
| `--json` |  |
| `--evidence` | How each row is known, and how old that is |

## `agentseam tier-table`

The enforcement table, derived from the matrix

Usage:

```text
agentseam tier-table [-h] [--event EVENT] [--fail-closed]
```

| Argument | Help |
| --- | --- |
| `--event EVENT` default `pre_tool` | Gate to report on (default: pre_tool) |
| `--fail-closed` | Read the table for an install made with fail_closed=True |

## `agentseam doctor`

What is wired here; flag stale capability claims

Usage:

```text
agentseam doctor [-h] [--repo REPO]
```

| Argument | Help |
| --- | --- |
| `--repo REPO` default `.` |  |

## `agentseam probe`

Measure what an agent's hooks actually enforce, against a driver

Usage:

```text
agentseam probe [-h] {list,run,conformance} ...
```

No arguments besides `-h, --help`.

Subcommands:

- `agentseam probe list`
- `agentseam probe run`
- `agentseam probe conformance`

## `agentseam probe list`

The trials and what each measures

Usage:

```text
agentseam probe list [-h]
```

No arguments besides `-h, --help`.

## `agentseam probe run`

Run trials against --driver; a table, or --report for submission

Usage:

```text
agentseam probe run [-h] --agent AGENT [--trial TRIAL]
                    [--event {prompt_submit,pre_tool,stop}] [--driver DRIVER] [--record]
                    [--keep] [--json] [--report] [--agent-version AGENT_VERSION]
                    [--reporter REPORTER]
```

| Argument | Help |
| --- | --- |
| `--agent AGENT` (required) |  |
| `--trial TRIAL` | Repeatable; default is all |
| `--event` one of: prompt_submit, pre_tool, stop default `pre_tool` | Which gate to wire the probe at (default: pre_tool) |
| `--driver DRIVER` | 'reference', 'recorded', 'harness' (the invocation agentseam.harness records for --agent), or a shell template containing {prompt}; default: 'recorded' if a recording covers --agent at --event, else 'reference' |
| `--record` | Freeze this run into data/recordings/\<agent\>@\<agent-version\>.json |
| `--keep` | Leave the scratch workspace for inspection |
| `--json` |  |
| `--report` | Emit a submittable evidence report |
| `--agent-version AGENT_VERSION` | The agent build these trials ran against |
| `--reporter REPORTER` | How you want crediting, e.g. @handle |

## `agentseam probe conformance`

Compare the recorded agents; exit non-zero on a seam gap

Usage:

```text
agentseam probe conformance [-h] [--event {prompt_submit,pre_tool,stop}]
```

| Argument | Help |
| --- | --- |
| `--event` one of: prompt_submit, pre_tool, stop | One gate (default: all recorded) |

## `agentseam install`

Wire a handler command into an agent's config

Usage:

```text
agentseam install [-h] [--events [EVENTS ...]] [--matcher MATCHER] [--watch FILE]
                  [--repo REPO]
                  agent command
```

| Argument | Help |
| --- | --- |
| `agent` (required) | Agent name, or 'all' |
| `command` (required) | Command the agent should run for each event |
| `--events [EVENTS ...]` | Canonical events (default: pre_tool) |
| `--matcher MATCHER` | Vendor tool matcher, e.g. 'Write\|Edit' |
| `--watch FILE` | A file name file_changed watches (repeatable) |
| `--repo REPO` default `.` |  |

## `agentseam instructions`

Write standing instructions to every agent's file

Usage:

```text
agentseam instructions [-h] [--text TEXT] [--agents [AGENTS ...]] [--repo REPO] [--dry-run]
                       [--list]
```

| Argument | Help |
| --- | --- |
| `--text TEXT` | Instruction text; omit to read stdin |
| `--agents [AGENTS ...]` | Target agents (default: all) |
| `--repo REPO` default `.` |  |
| `--dry-run` |  |
| `--list` | Show what exists instead of writing |

## `agentseam permissions`

Each agent's permission surface; render a policy into it

Usage:

```text
agentseam permissions [-h] [--rule ACTION:CAPABILITY[:SPEC]] [--agents [AGENTS ...]]
```

| Argument | Help |
| --- | --- |
| `--rule ACTION:CAPABILITY[:SPEC]` |  |
| `--agents [AGENTS ...]` | Target agents (default: all with a recorded model) |

## `agentseam packaging`

Where each agent looks for skills, subagents and commands

Usage:

```text
agentseam packaging [-h]
```

No arguments besides `-h, --help`.

## `agentseam uninstall`

Remove only agentseam's entries

Usage:

```text
agentseam uninstall [-h] [--repo REPO] agent
```

| Argument | Help |
| --- | --- |
| `agent` (required) | Agent name, or 'all' |
| `--repo REPO` default `.` |  |

## Exit codes

- 2: argparse rejected the arguments. The site's tests run each command and subcommand with an unknown option and check that it exits 2.
- This page lists no other codes. The runs on Use agentseam without chock show the code each one returned.

## Help as printed

This is what `agentseam --help` prints, from the same parser.

```text
usage: agentseam [-h] [--version]
                 {agents,matrix,tier-table,doctor,probe,install,instructions,permissions,packaging,uninstall}
                 ...

agentseam CLI: inspect the matrix, wire hooks, audit a machine.

positional arguments:
  {agents,matrix,tier-table,doctor,probe,install,instructions,permissions,packaging,uninstall}
    agents              list known agents
    matrix              what each agent can enforce, per event
    tier-table          the enforcement table, derived from the matrix
    doctor              what is wired here; flag stale capability claims
    probe               measure what an agent's hooks actually enforce, against a driver
    install             wire a handler command into an agent's config
    instructions        write standing instructions to every agent's file
    permissions         each agent's permission surface; render a policy into it
    packaging           where each agent looks for skills, subagents and commands
    uninstall           remove only agentseam's entries

options:
  -h, --help            show this help message and exit
  --version             show program's version number and exit
```


---

Built from engine [5a4b6287a46e](https://github.com/open-coder-ai/chock/commit/5a4b6287a46e07f9f856d9bbe10622bd1ff2e021) and catalog [1e60d211c1bb](https://github.com/open-coder-ai/chock-catalog/commit/1e60d211c1bb767152c6ab0167932da06ab3a10f).