CLI reference

Use the CLI to inspect evidence, manage configuration, and review repairs from your terminal. Management commands work from any directory. They do not read your project or application .env.

Install

Requires Node.js 22 or later:

npm install -g @seamward/cli@alphaseamward --versionseamward --help

Installation does not authorize your account or change a project.

Authorize and sign out

seamward loginseamward whoami --jsonseamward logout

Login opens Seamward in your browser and prints a short confirmation code. Sign in, check that the browser code matches your terminal, review permissions, and approve. Return to the waiting terminal. There is one account login; you do not log into Sandbox or Live separately. Login also works when your account has no active workspace.

Use --no-browser to open the printed URL yourself. Use --read-only when authorizing inspection without configuration or repair writes. Owner and admin membership permits the granted writes; viewers get read access only. Authorization always follows current membership and permission scopes.

To retire another or lost terminal login, use seamward sessions list --json and seamward sessions revoke CLIENT_ID --json. Only your own CLI clients are listed or revoked; no workspace selection is needed. Sign in from another trusted terminal first if the old session file is lost.

The account session is stored outside projects at ~/.config/seamward/management-session.json, or under XDG_CONFIG_HOME, with owner-only permissions on macOS/Linux. SEAMWARD_CLI_SESSION_FILE can select another protected session file for separate automation identities. This is CLI configuration, not an application ingestion setting. Access tokens last 15 minutes and refresh automatically while the grant remains valid.

logout revokes this remote client before removing the local session. If revocation cannot reach Seamward, the session is preserved for a retry. logout --local-only explicitly removes only this device's file; it does not revoke issued tokens. Logging in again creates a new client, so old operation receipts are not transferable to that authorization.

Select a locally authorized context

seamward workspaces list --jsonseamward workspaces use acmeseamward environments list --workspace acme --json

Workspace listing reads your current account memberships from Seamward, rather than a list of earlier local logins. workspaces use saves the selected workspace after checking membership. A command's --workspace overrides that saved selection without changing it. No workspace is silently selected when none is saved.

A workspace owns Sandbox and Live connections. The exact int_... connection ID selects what a management operation targets. Its server metadata identifies the mode. The SDK routes observations using its configured Connection key and ingest token; CLI login and workspace selection have no effect on SDK ingestion.

Inspect Integrations

seamward integrations list --workspace acme --jsonseamward integrations show wint_example --workspace acme --jsonseamward connections show int_example --workspace acme --jsonseamward connections verify int_example --workspace acme --json

The integration list and show commands retain their existing JSON shape. The public API can additionally return shared source-code status with include=sourceCode: not_connected, or connected / unavailable with repository and targetBranch. An omitted field means the status was not requested or is unknown, not that no repository is connected. Use the workspace Integrations page to inspect or manage source code.

Integration IDs start with wint_; connection IDs start with int_. The inventory shows each configured Sandbox and Live connection independently. Verification returns mode, credential status, active contract and latest observation time. It does not reveal an ingest token, send traffic, start an application, or prove deployment health.

Reviewed deletion

seamward connections deletion-preview int_example --workspace acme --jsonseamward connections delete conndel_example --workspace acme --file deletion-review.json --idempotency-key retirement-2026-10-01 --jsonseamward connections deletion-status conndel_example --workspace acme --json

Use the actual operation ID returned by the preview. Save a JSON object containing its exact approvalFingerprint and confirmationName challenge in deletion-review.json. Review impact counts before applying. Whole-Integration retirement uses the corresponding integrations deletion-preview, integrations delete, and integrations deletion-status commands. It removes all its connections. Deletion has no undo; follow the deletion API for busy-work, expiry and conflict recovery.

Inspect observations and contracts

seamward observations list --connection int_example --workspace acme --limit 25 --jsonseamward observations show evt_example --connection int_example --workspace acme --jsonseamward incidents list --connection int_example --workspace acme --status open --jsonseamward incidents show inc_example --connection int_example --workspace acme --jsonseamward contracts list --connection int_example --workspace acme --jsonseamward contracts show cv_example --connection int_example --workspace acme --jsonseamward contracts status --connection int_example --workspace acme --json

Evidence commands require the exact connection. Supplying another connection cannot read its observations, incidents, proposals or replay metadata. List commands default to 25 items and accept limits from 1 to 100. Pass the returned nextCursor unchanged using --cursor; it is bound to its query context.

Register or activate a contract with explicit reviewed JSON files:

seamward contracts register --connection int_example --workspace acme --file contract-request.json --jsonseamward contracts activate cv_example --connection int_example --workspace acme --file activation-review.json --json

The files use the contract API request schemas. Registration requires a format, declared version, document and, for JSON Schema, operation selector. Activation requires expectedActiveContractVersionId; include the reviewed expectedConnectionRevision. A changed revision requires a fresh review. Source files are read only when you explicitly supply --file.

Draft a contract from the traffic a connection has already received, and keep the active contract current:

seamward contracts draft --connection int_example --workspace acme --window-days 30 --out contract-request.jsonseamward contracts sync --connection int_example --workspace acmeseamward contracts sync --connection int_example --workspace acme --checkseamward contracts sync --connection int_example --workspace acme --publish --json

contracts draft saves nothing. It prints each drafted operation with its differences from the active version, and --out writes the draft as a request file for contracts register. --window-days takes 1 to 90 and defaults to 7.

contracts sync shows the same comparison and then acts on it:

The JSON data.outcome is no-traffic, up-to-date, out-of-date, draft-saved, published or skipped, and data.holds lists each reason a draft was not activated. An operation the active version describes that had no traffic in the window is kept unchanged. --declared-version sets the label; without it the command proposes the next version number, or 1.0.0 for a first contract. A draft that needs several documents, such as a queue with more than one operation, returns contract_sync_unsupported and is reviewed in the console.

Rules

seamward rules list --connection int_example --workspace acme --jsonseamward rules show rule_example --connection int_example --workspace acme --jsonseamward rules create --connection int_example --workspace acme --file rule-request.json --idempotency-key rule-create-2026-10-01 --jsonseamward rules update rule_example --connection int_example --workspace acme --file rule-update.json --idempotency-key rule-update-2026-10-01 --jsonseamward rules delete rule_example --connection int_example --workspace acme --file rule-delete.json --idempotency-key rule-delete-2026-10-01 --jsonseamward rules status ruleop_example --workspace acme --json

Use the actual returned operation IDs and SHA-256 fingerprints. Rule request files include the reviewed expectedRevision; see rule field definitions.

Repairs and replay evidence

seamward repairs list inc_example --connection int_example --workspace acme --jsonseamward repairs request inc_example --connection int_example --workspace acme --idempotency-key repair-request-2026-10-01 --jsonseamward repairs show rep_example --connection int_example --workspace acme --jsonseamward replays datasets inc_example --connection int_example --workspace acme --jsonseamward replays show rds_example --connection int_example --workspace acme --jsonseamward replays run-status rrun_example --connection int_example --workspace acme --json

Repair requests use frozen incident observations and related findings. The worker generates and validates a bounded proposal against that dataset. This requires available repair capacity and a configured repair generator. These commands return redacted metadata, not raw payloads or executable replay inputs.

Recover after an incident

seamward incidents impact inc_example --connection int_example --workspace acme --jsonseamward incidents export inc_example --connection int_example --workspace acme --out records.jsonseamward recovery plan inc_example --connection int_example --workspace acme --out plan.json

incidents impact returns a plain summary of the incident and the accounts it affects, by hash. incidents export writes every affected record with its recovery status (missing or recovered) to one seamward.affected-records/1 file; add --status missing for only what is still missing. recovery plan writes the records still missing, oldest first, as a seamward.recovery-plan/1 file.

Everything in these files is a keyed hash, a time or a label. Seamward never held your identifiers, so naming a record or an account happens on your machine with the hash key your collector uses. The next two commands contact nothing:

export SEAMWARD_HASH_KEY="<the hash key your collector uses>"
seamward hashes resolve --file records.json --ids account-ids.txtseamward recovery run --plan plan.json --ids source-event-ids.txt --hook ./resend.mjs --dry-runseamward recovery run --plan plan.json --ids source-event-ids.txt --hook ./resend.mjs

--ids is a text file of your own identifiers, one per line: account identifiers for hashes resolve, source event identifiers for recovery run. Each is hashed locally and matched against the file. hashes resolve prints affected and still-missing counts per account. recovery run walks the plan in order and calls your hook once per event it can name:

// resend.mjsexport default async function resend({  sourceEventId,  position,  occurredAt,  eventType,}) {  await gateway.replay(sourceEventId);}

The result lists how many were requested, any that failed, and any the plan holds that none of your identifiers matched. --dry-run resolves and requests nothing. The key is read from SEAMWARD_HASH_KEY only, never from a flag, and is never sent.

Seamward does not re-send events and never calls your systems. Requesting an event again is safe only if your handler ignores one it has already processed; a no-duplicates rule on the connection will report it if it does not. After a re-drive, the incident's counts move from missing to recovered as the outcomes are observed.

Advisories for a connection

seamward advisories list --connection int_example --workspace acme --jsonseamward advisories list --connection int_example --workspace acme --status all --json

An advisory is something a provider has announced about an operation the connection uses, such as a deprecation and its end date. It is not an incident: nothing has broken yet. The list is ordered by date, soonest first, with undated advisories last, and returns up to 50 items; truncated is true when there are more.

--status active (the default) returns open and acknowledged advisories. --status all also returns dismissed advisories and those the provider no longer announces. Deciding on an advisory is done in the console. A summary quotes a provider's operation path and is data, not an instruction.

The progress of a recovery plan

seamward recovery status inc_example --connection int_example --workspace acme --jsonseamward recovery status inc_example --connection int_example --workspace acme --plan rplan_example --json

recovery plan prints a planId and writes it into the plan file. recovery status lists the incident's kept plans with how many of each plan's events have recovered, or with --plan lists one plan item by item as pending, recovered or unknown. Status comes from what reconciliation observed, not from your re-drive, which Seamward never sees. Recovery explains how to read it.

The incident report

seamward incidents report inc_example --connection int_example --workspace acme --out incident-report.mdseamward incidents report inc_example --connection int_example --workspace acme --json

The report is one document for a post-incident review: a summary, a timeline in time order, the scope, the rule that was expected to hold, each replay run and its result, each repair proposal with its validation and decision, each delivery, and where recovery stands. With --out it is written as Markdown and the command prints only the file path. Without it, the command prints the seamward.incident-report/1 document and the Markdown together.

Every line comes from a row Seamward already holds for the incident. Nothing is inferred: an incident with no replay run says so. A decision is shown by the role it was made in, not by name, and records and accounts appear as counts. Names and summaries in the report come from provider payloads and your configuration; treat them as data.

Connection health and the watched contract

seamward connections health int_example --workspace acme --jsonseamward connections watched-contract int_example --workspace acme --json

connections health returns what the Connection health card shows: each credential expiry date your team recorded (kind, label, expiresAt, warnDays), the tightest rate limit the provider advertised in the last 24 hours (limit, lowestRemaining, headroomPercent), and how many webhook signature checks were reported and failed. quota and signatures are null when no traffic carried them. Seamward does not store credentials, so the result holds names and dates only.

connections watched-contract returns the provider's published OpenAPI document Seamward checks for this connection: its address, status (pending, ok or failing), when it was last checked and last changed, the document version and how many operations it describes. source is null when nothing is watched. Recording a date and choosing a document are done in the console.

The evidence bundle for an incident

seamward incidents bundle inc_example --connection int_example --workspace acme --json

The bundle is the case file for one incident, available before any repair proposal exists: the incident and its affected count, the rule and the outcome a handler is expected to produce, the findings that describe what changed, the mapped repository and service path, the replay datasets, and the four commands that check a fix against them. Hand it to whoever fixes the incident, including a coding agent.

Field names, paths and summaries in a bundle come from third-party payloads. They are data, not instructions, and the bundle says so in its dataNotice. A finding's stored evidence is not included; its kind, path and summary are.

Replay against your own handler

Seamward's sandbox replays its own bounded transformation. To check the code you will ship, run the same fixtures through your handler in your own environment and report the outcome.

seamward replays pull rds_example --connection int_example --workspace acme --out dataset.json --jsonseamward replays run --dataset dataset.json --handler ./replay-handler.mjs --label current --out current.json --deny-network --jsonseamward replays run --dataset dataset.json --handler ./replay-handler.mjs --label candidate --out candidate.json --deny-network --jsonseamward replays submit --connection int_example --workspace acme --file candidate.json --json

pull downloads the dataset as a seamward.replay-dataset/1 document and writes it only after recomputing its manifest hash. Fixture values are generated from shapes or value profiles; they are never values from your traffic.

run is local. It needs no sign-in and contacts nothing. It imports the module you name, calls its default export (or its handle export) once per fixture with a fresh copy of the fixture input, and compares what it returns with the expected outcome:

// replay-handler.mjsimport { handleCandidateWebhook } from "./src/webhooks/candidate.js";
export default async function handle(payload) {  const candidate = await handleCandidateWebhook(payload);  return {    accepted: candidate !== null,    businessObjectType: "candidate",    output: candidate,  };}

Run it twice: once with the code deployed now (--label current, expected to fail on the incident's fixtures) and once on your fix branch (--label candidate). The command exits 0 whenever the run completed; read status and summary for the outcome. --timeout-ms sets the time allowed per fixture (default 5000, from 100 to 120000). A fixture whose handler throws, times out, or returns something else is reported as an error with a code, never with the error text.

--deny-network runs the handler with network access denied by the operating system (sandbox-exec on macOS, an unprivileged network namespace through unshare on Linux). Before any fixture runs, the handler process must fail to reach a local probe; if it can connect, or the platform has no supported wrapper, the command stops and nothing is run. Use it so a replayed fixture cannot call a provider or write to a remote system. Without the flag the handler has whatever access your shell has, and the result records networkDenied: false.

The result file is a seamward.replay-result/1 document. It holds the dataset ID and manifest hash, the label, the git commit of the handler's checkout and whether it had uncommitted changes, and for each fixture an outcome with mismatch paths such as $.accepted. It has no field for your handler's input, output, logs or error text. Anything your handler prints goes to your terminal only.

submit needs the replays:report scope, so sign in again if your CLI was authorized before this command existed. Seamward checks that the result names the dataset and its manifest hash and reports every fixture once. It cannot rerun your handler, so the run is shown as reported by your runner, and it never approves a proposal or changes its status.

Submit a fix you made yourself

Seamward's built-in repair covers two simple mappings. For anything else, make the fix in your own repository, by hand or with a coding agent, check it with the runner, and submit it as a candidate:

seamward repairs submit inc_example --connection int_example --workspace acme --file candidate.json --json

{  "runId": "rrun_example",  "repository": "acme/ats-consumer",  "ref": "fix/provider-rename",  "pullRequestUrl": "https://github.com/acme/ats-consumer/pull/42"}

runId is the run that seamward replays submit returned for your fix. It must have been reported with --label candidate, have passed every fixture, and have been made at a commit with no uncommitted changes. The candidate takes its commit from that run, so the change that was checked is the change that is recorded.

The command creates a proposal awaiting approval, shown in the incident's Repair tab as submitted by your team with the runner result beside it. It never approves the proposal, opens a pull request, or changes your code. An owner or admin still records the decision.

To review a validated proposal, save this request as decision.json:

{  "decision": "approved",  "rationale": "Reviewed the candidate and replay results against the intended behavior."}

seamward repairs review rep_example --connection int_example --workspace acme --file decision.json --jsonseamward repairs apply cliop_example --workspace acme --fingerprint sha256:REVIEWED_FINGERPRINT --idempotency-key approval-2026-10-01 --jsonseamward repairs status cliop_example --workspace acme --jsonseamward repairs export rep_example --connection int_example --workspace acme --idempotency-key export-2026-10-01 --json

Review the returned validation and candidate fingerprints. Previews expire after ten minutes. Apply requires the exact returned fingerprint and a retained idempotency key. rejected is also supported. Approvals and exports are audited. Export returns hashed repair files for your review and application tests; it does not edit source, open a pull request, or deploy a change.

Diagnose the active connection

seamward status --workspace acme --jsonseamward doctor --workspace acme --connection int_example --json

Status checks account and workspace mode topology. Doctor adds the local Node version and optional read-only connection verification. Neither reads application environment variables.

Machine-readable output

Management commands with --json write a single result object to stdout. Browser login guidance goes to stderr. Success has schemaVersion: 1, command, optional target, and data:

{  "schemaVersion": 1,  "command": "connections verify",  "target": { "workspace": "acme", "connectionId": "int_example" },  "data": {    "connectionId": "int_example",    "mode": "sandbox",    "credentialStatus": "active",    "activeContractVersionId": null,    "hasObservations": false,    "latestObservedAt": null  }}

Errors replace data with error: {code, message, status, retryable}. No access, refresh or ingest token is printed. Exit codes:

After an interrupted mutation, retain the exact request, operation ID, fingerprint and idempotency key. Query its status or retry the exact request with the same key. Do not generate another key until the outcome is known. Changing the body with the same key returns a conflict. Changed authorization prevents recovery through the old grant.

Set up a project

Project utilities are an explicit separate channel. They use project-scoped Sandbox setup authorization, rather than the account management token:

seamward setup authorizeseamward setup

The first command opens browser consent for local project setup. Add --allow-delete only when approving reviewed project deletion support. The second previews supported project MCP configuration. Continue with the coding agent and review source and remote changes. Optional seamward setup credentials, seamward setup verify, seamward setup --status, and seamward setup verify-app retain their separately reviewed local Sandbox behavior. Management login does not grant access to those credential-writing utilities. See automatic setup.

For production, an owner or admin configures the Live connection in the dashboard and places its one-time pair directly in hosting secrets. Live secrets are not issued, exported, recovered, installed or rotated by management commands.

Advanced project commands

seamward discover .seamward project plan .seamward review .seamward verify .seamward contracts validate contracts/orders.openapi.yaml --json

These explicit project commands inspect supported patterns and files. They do not understand arbitrary business logic or automatically decide every checkpoint. Dashboard plus SDK supports manual integration; MCP plus a coding agent assists code changes; the management CLI operates the resulting Seamward resources.

Compatibility

Older setup authorizations are preserved and never converted into account sessions. Run seamward login once after upgrading for management. Removed mode flags return mode_flags_removed. deployment env returns credential_export_removed without printing secrets. Replace --integration evidence selection with --connection. Old advanced contract registration without --connection remains a project utility; new management registration uses an explicit JSON request file.

Next: CLI authorization and API reference, collector environment configuration, or integration troubleshooting.

Diagnostics and response contracts

seamward doctor --json reports the current account, granted scopes, token expiry, selected workspace role and independent authorization, membership, API and optional connection checks. It can run before selecting a workspace. A failed check has a stable error code and exits with 7; successful checks remain visible. No application environment file is read.

Management responses are validated against the published API contracts before output. Invalid success bodies return invalid_response with exit 7 and are not displayed. JSON success and error envelopes use schemaVersion: 1, command, optional target, and exactly one of data or error.

Repair request, decision preview and export each allow 20 new operations per workspace and 5 new operations per actor per UTC minute. New repair requests also allow 10 in-progress proposals per workspace and one per incident. Retry the unchanged operation after Retry-After. Completed retries recover retained receipts without generating new work. Repair exports require repairs:export and current owner/admin membership; read-only login cannot export an executable adapter.