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.
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.
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.
trace and test report what the engine would do, which is not the same as
which rules match. The engine applies the first matching rule and returns, so at
most one rule is reported as applied; rules ordered after it are reported with
miss_code: shadowed.
This matters when you load a directory. Rule order is filename-lexical and there
is no priority field, so a broad rule silently disables every narrower rule that
sorts after it. In the shipped set, mcp_tool_call_argument_merge requires only
method equals tools/call while mcp_tool_call_argument_rewrite additionally
requires params.name contains lookup: the broader rule sorts first and the
specific one can never fire. Ten of the twenty shipped rules are unreachable when
rules/ is applied whole.
Point --rules at a single file, or a directory you assembled, when you need a
specific rule to fire. seam rules test --rules <dir> --expect-rule <id> fails
when the rule you want is shadowed, so run it before arming a live target.
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.
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.
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 tail¶
Use this to watch recent transcript records like a live operator feed.
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 profile list and seam profile run¶
Profiles are optional presets that expand to ordinary flags. Explicit operator flags win.
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 version¶
Use this in reports, release smokes, and operator handoffs.