Skip to content

Seam CLI

Passive Tap

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

The resulting transcript can be passed to meshmapper.

tap defaults to 127.0.0.1:8400. Non-loopback listeners require --allow-remote-listen. Upstream redirects are not followed by default; use --allow-redirects only when redirect targets are authorized and in scope. Optional profiles expand to these same ordinary flags; they do not block direct low-level operation.

Active Proxy

seam 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-rule a2a_prompt_laundering_replace \
  --expect-min-rewrites 1 \
  --summary-json rewrite.summary.json

Active proxy transcripts preserve both before and rewritten after messages for downstream graph and finding evidence.

proxy uses the same loopback and redirect defaults as tap.

Live offensive controls make expected outcomes explicit:

  • --expect-rule <id> may be repeated.
  • --expect-min-matches <n> fails if too few rules match.
  • --expect-min-rewrites <n> fails if too few rewrites are applied.
  • --fail-if-no-rewrite is shorthand for requiring at least one rewrite.
  • --summary-json out.json writes counters for records, matched rules, rewrites, touched decoded paths, failures by rule, and latest transcript hash.

These controls also apply to seam stdio proxy and seam session start --mode proxy.

Remote data-plane operation stays available for authorized work:

seam proxy --listen 0.0.0.0:8400 --allow-remote-listen \
  --upstream http://10.10.0.25:8500 \
  --rules rules/ \
  --transcript rewrite.json \
  --schema schemas/transcript.schema.json

MCP stdio

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_spoof.yaml \
      --transcript stdio.json \
      --schema schemas/transcript.schema.json \
      -- examples/mcp-stdio-fixture.py

Operator Helpers

For every command and flag, see the complete command reference.

seam doctor
seam doctor --json
seam rules list --rules rules/
seam rules test --rules rules/ --fixture examples/a2a-agent-card.json --expect-rule a2a_card_spoof
seam rules pack --rules rules/ --out rule-pack.json
seam rules explain --rules rules/ --rule a2a_prompt_laundering_replace
seam rules trace --rules rules/ --transcript rewrite.json
seam rules trace --pack rule-pack.json --transcript rewrite.json
seam transcript inspect --transcript rewrite.json --schema schemas/transcript.schema.json --decoded
seam transcript redact --transcript rewrite.json --out rewrite.redacted.json --schema schemas/transcript.schema.json
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
seam session status --transcript rewrite.json --schema schemas/transcript.schema.json
seam session tail --transcript rewrite.json --limit 5
seam session stop
seam profile list
seam profile run lab --mode proxy --upstream http://127.0.0.1:8500 \
  --rules rules/ --transcript lab.json --schema schemas/transcript.schema.json

These commands are diagnostic and operator-facing. They validate local prerequisites, show rule summaries, test rule matches against fixtures, replay transcripts through rule matching, verify and summarize transcripts, and expand visible profile manifests into ordinary tap or proxy flags. JSON output is available for workbench automation where noted.

rules test and rules trace include per-rule missed-match explanations. JSON output reports exact field mismatches, where predicate misses, ineligible protocols, missing decoded paths, and transform errors. Use this when a live proxy summary shows zero matches.

API-managed proxy intercepts can also carry expected-match settings:

curl -X POST http://127.0.0.1:8401/intercept/start \
  -H 'Content-Type: application/json' \
  -d '{"mode":"proxy","listen":"127.0.0.1:8400","upstream":"http://127.0.0.1:8500","rules":"rules/","expect_rules":["a2a_prompt_laundering_replace"],"expect_min_rewrites":1}'
curl -X POST http://127.0.0.1:8401/intercept/stop

The stop response includes the final live summary and expectation errors, if any. When an expected rule did not match, API summaries include miss_reasons such as field mismatches, missing decoded paths, or unloaded expected rules. These are operator diagnostics and may include decoded field values; treat them as sensitive live-run output rather than report-safe material.

Injection Helpers

The shipped rules include insert/merge payload-file examples:

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

Version And Release

seam version
seam version --json
bash scripts/build-release.sh --version v0.1.0
bash scripts/smoke-release.sh

Release archives include the binary, schemas, rules, scenarios, examples, QUICKSTART.md, and checksums. The smoke script validates the current-platform archive before a tagged release.

Robustness

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

Robustness bundles support the R/R/R methodology. They complement, but do not replace, Assay oracle proof.