Seam Command Reference¶

This reference is for live operator use. Seam is the in-path tool: use it to capture, rewrite, trace rules, inspect transcripts, and wrap local MCP servers. AIT can orchestrate these commands, but Seam remains the low-level instrument.

`seam tap`¶

Use tap when you want to observe traffic without mutation.

Required: --upstream, --transcript, --schema.

Important flags: --listen, --session, body/SSE/WebSocket limits, --record-failure-policy, --allow-remote-listen, --allow-redirects.

seam tap --listen 127.0.0.1:8400 \
  --upstream http://127.0.0.1:8500 \
  --transcript out.json \
  --schema schemas/transcript.schema.json

Output: a hash-chained transcript with before records only. Common failures are missing upstream, unavailable listen port, schema path errors, and capture-limit failures.

`seam proxy`¶

Use proxy when you want Seam to actively rewrite eligible complete messages.

Required: --upstream, --rules, --transcript, --schema.

Important flags: --transform-failure-policy fail-closed|fail-open, --expect-rule, --expect-min-matches, --expect-min-rewrites, --fail-if-no-rewrite, --summary-json.

seam proxy --listen 127.0.0.1:8400 \
  --upstream http://127.0.0.1:8500 \
  --rules rules/a2a_message_part_insert.yaml \
  --transcript rewrite.json \
  --schema schemas/transcript.schema.json \
  --expect-rule a2a_message_part_insert \
  --expect-min-rewrites 1 \
  --summary-json rewrite.summary.json

Output: transcript records with before, after, and rule_applied for rewrites; optional live summary JSON with counters, rules matched, rewrites, touched decoded paths, failures, and latest hash.

`seam stdio tap`¶

Use stdio tap to observe a local MCP server without changing stdin/stdout traffic.

printf '{"jsonrpc":"2.0","id":"call-1","method":"tools/list"}\n' \
  | seam stdio tap --command python3 \
      --transcript stdio.json \
      --schema schemas/transcript.schema.json \
      -- examples/mcp-stdio-fixture.py

Output: MCP JSON-RPC request/response records with decoded.transport: stdio. Child stderr is forwarded to stderr and is not decoded.

`seam stdio proxy`¶

Use stdio proxy when wrapping a local MCP server and rewriting complete JSON-RPC lines.

printf '{"jsonrpc":"2.0","id":"call-1","method":"tools/call","params":{"name":"echo","arguments":{"account":"ORIGINAL"}}}\n' \
  | seam stdio proxy --command python3 \
      --rules rules/mcp_stdio_argument_merge.yaml \
      --transcript stdio-rewrite.json \
      --schema schemas/transcript.schema.json \
      --expect-rule mcp_stdio_argument_merge \
      --summary-json stdio.summary.json \
      -- examples/mcp-stdio-fixture.py

Common failures: no complete newline-delimited JSON-RPC line, child launch failure, transform failure, or stdout carrying non-protocol logs from the wrapped server.

`seam api`¶

Use the API when another tool, such as AIT or Assay, needs to start/stop one managed intercept and deliver HTTP probes through it.

seam api --listen 127.0.0.1:8401 \
  --transcript api.json \
  --schema schemas/transcript.schema.json

Primary endpoints: POST /intercept/start, POST /intercept/stop, GET /messages, GET /transcript, POST /rules/apply, and POST /deliver.

`seam rules list`¶

Use this before a run to verify that a rules file or directory loads.

seam rules list --rules rules/ --json

Output includes rule id, description, match summary, predicates, and mutation summary.

`seam rules test`¶

Use this to test a rule against a single fixture without starting a proxy.

seam rules test \
  --rules rules/a2a_message_part_insert.yaml \
  --fixture examples/a2a-message-send.json \
  --expect-rule a2a_message_part_insert \
  --json

Output reports matched rules, per-rule match/miss reasons, eligibility, and transform errors.

`seam rules trace`¶

Use this after a capture to answer why rules did or did not fire.

seam rules trace --rules rules/ --transcript rewrite.json --json

Trace replays transcript before and after messages through rule matching only. It does not forward traffic or change the transcript.

`seam rules explain`¶

Use this when authoring or reviewing a rule.

seam rules explain \
  --rules rules/mcp_tool_call_argument_merge.yaml \
  --rule mcp_tool_call_argument_merge \
  --json

Output includes match fields, predicates, mutations, eligible transports, touched decoded paths, and likely failure modes.

`seam rules pack`¶

Use this to produce an operator artifact describing the active rule set.

seam rules pack --rules rules/ --out rule-pack.json --json

Rule packs are not shared schemas; they are handoff artifacts for trace/replay workflows.

`seam transcript verify`¶

Use this to verify schema validity and transcript hash chain integrity.

seam transcript verify \
  --schema schemas/transcript.schema.json \
  --transcript rewrite.json

Failures identify the first bad record, bad prev_hash, bad base64, schema mismatch, or hash mismatch.

`seam transcript inspect`¶

Use this to summarize protocols, kinds, rule ids, decoded keys, and latest hash.

seam transcript inspect \
  --schema schemas/transcript.schema.json \
  --transcript rewrite.json \
  --decoded \
  --json

`seam transcript redact`¶

Use this only when producing a review copy. The raw transcript remains source evidence.

seam transcript redact \
  --schema schemas/transcript.schema.json \
  --transcript rewrite.json \
  --out rewrite.redacted.json \
  --json

`seam session start`¶

Use this as a foreground wrapper over tap or proxy when you want session vocabulary and the same low-level flags.

seam session start --mode proxy \
  --listen 127.0.0.1:8400 \
  --upstream http://127.0.0.1:8500 \
  --rules rules/ \
  --transcript rewrite.json \
  --schema schemas/transcript.schema.json \
  --expect-min-rewrites 1

`seam session status`¶

Use this to get a quick transcript-backed session summary.

seam session status \
  --schema schemas/transcript.schema.json \
  --transcript rewrite.json \
  --json

`seam session tail`¶

Use this to watch recent transcript records like a live operator feed.

seam session tail --transcript rewrite.json --limit 20

seam session tail --transcript rewrite.json --follow

`seam session stop`¶

Standalone Seam sessions run in the foreground; stop them with Ctrl-C or SIGTERM. API-managed sessions stop with POST /intercept/stop.

seam session stop

`seam profile list` and `seam profile run`¶

Profiles are optional presets that expand to ordinary flags. Explicit operator flags win.

seam profile list --profiles profiles --json

seam profile run lab --mode proxy \
  --upstream http://127.0.0.1:8500 \
  --rules rules/ \
  --transcript lab.json \
  --schema schemas/transcript.schema.json

`seam robustness run`¶

Use this to run deterministic local scenarios against Seam transports and rule packs.

seam robustness run \
  --scenario scenarios/a2a_card_spoof.yaml \
  --out bundles \
  --schema schemas/transcript.schema.json \
  --repetitions 3

`seam doctor`¶

Use this to check local operator prerequisites.

seam doctor --schema schemas/transcript.schema.json --rules rules/ --json

`seam version`¶

Use this in reports, release smokes, and operator handoffs.

seam version
seam version --json

Seam Command Reference¶

seam tap¶

seam proxy¶

seam stdio tap¶

seam stdio proxy¶

seam api¶

seam rules list¶

seam rules test¶

seam rules trace¶

seam rules explain¶

seam rules pack¶

seam transcript verify¶

seam transcript inspect¶

seam transcript redact¶

seam session start¶

seam session status¶

seam session tail¶

seam session stop¶

seam profile list and seam profile run¶

seam robustness run¶

seam doctor¶

seam version¶