CLI reference

The seamward command gives developers one entry point for authorization, project setup, diagnostics, and read-only inspection of the active workspace environment.

Install

Install the command once. Installation does not open a browser, create a configuration directory, or modify the current project.

npm install -g @seamward/cli@alpha

Confirm the installed command:

seamward --versionseamward --help

Authorize and sign out

seamward loginseamward whoamiseamward logout

login prints the authorization URL and waits for Enter before opening the browser. Select a workspace, approve access, and wait for the Seamward success screen. The browser stays on Seamward while the CLI polls for the approved device grant and continues automatically. No local callback page is opened in the browser.

Login defaults to Sandbox. Use seamward login --live to authorize Live. Normal login does not grant deletion. Use seamward login --allow-delete only for a reviewed Integration deletion. Every configured connection must belong to that selected one-mode grant; use the workspace-key API to remove a workflow with both modes configured.

The authorization and active selection are stored outside the repository with owner-only file permissions. logout removes the Sandbox authorization by default. Use logout --live to remove another environment without signing out the others. To invalidate already issued access and refresh tokens, revoke the Project setup client in Workspace settings > MCP.

Set up a project

Run setup from one deployable backend service directory:

seamward setup

The command uses the Sandbox authorization unless an exact environment flag is supplied, previews the exact project files it would add or change, and installs project-scoped MCP configuration only after approval. It never reads or edits an environment file. Continue in the coding agent with one of the suggested prompts: set up, review only, check status, or review local credential saving. See Choose your next prompt. These requests do not bypass setup, runtime, or credential-saving approvals.

Finish local runtime setup

After the agent connects the Sandbox integrations, run:

seamward setup credentials

This interactive command selects a supported local environment destination, shows key names and conflicts without values, and asks before saving. No startup script or package.json is required. After saving, the CLI checks each saved Connection key and ingest token with Seamward. Exit 0 means every connection passed; a failed check exits 1 and leaves the saved file intact. This check does not start your app or send observations. No native agent dialog is involved. To check the selected file again:

seamward setup verify

CONNECTION VERIFIED describes this invocation only. It does not prove your app loads the file or emits observations. Start your app normally with that file loaded and check for real observations in Seamward. Read-only status commands are:

seamward setup --statusseamward setup --status --json

The credentials, verify and verify-app commands require Sandbox or an exact legacy Development grant and an interactive terminal; --yes, environment flags and JSON mutation are refused. --status is read-only and exits 0 only when local setup is current and every required Integration has an active (or not-applicable) contract and an accepted observation. Waiting, stale and incomplete states exit 1. Optional application testing is not required. Observed traffic is not proof of deployment or ongoing health; startup-test status remains separate.

File saving supports macOS/Linux and root .env and .env.local, independently of framework loaders. See local saving for safe recovery.

Explicit application diagnostic

This is not part of normal onboarding. Use it only when you specifically want an automated smoke test and already have reviewed startup and synthetic traffic scripts:

seamward setup verify-app

It requires a supported explicit Node --env-file loader. You select the startup script, readiness URL and traffic mapping, review their effects, and approve execution. It does not infer how arbitrary applications start. It stops its own processes after checking fresh observations and does not write credentials. Each retry needs a fresh review. Normal application observations do not require this test.

Setup never opens a browser. If the active authorization is missing, expired, or revoked, it exits before changing the project and instructs you to run seamward login, then rerun setup.

Use the automatic setup guide for the complete source review, remote approval, contract, runtime credential, and first-observation workflow.

After Sandbox source setup is verified, promote it without changing source:

seamward login --liveseamward setup --liveseamward deployment env --live

The promotion command previews remote Integration and contract effects, then applies them after confirmation. It never applies local source setup. Store the explicit deployment output in the hosting platform's secret manager and deploy the same source revision. There is no SEAMWARD_ENVIRONMENT variable.

Select a locally authorized context

seamward workspaces listseamward workspaces use <slug>seamward environments list

These commands list browser-authorized contexts already stored on this device. Authorize another workspace environment with the corresponding login flag. Commands always default to Sandbox. Add --live to the individual command to select Live. A previously selected Live authorization does not change that default.

Legacy workspaces

Until your workspace is migrated, use --development, --production, or --staging to select its exact stored environment. These flags do not provision another environment or grant access to a different object. Canonical workspaces use the default Sandbox and explicit --live. Conflicting flags fail before any network request or local write. Removal dates for legacy flags remain pending the migration release.

Inspect Integrations

seamward integrations listseamward integrations show <integration-id>seamward integrations delete <integration-id>

The commands are scoped to the active workspace environment. List and show are read-only. The list prints the stable wint_... Integration ID and the selected environment's int_... connection ID. Show and delete take the stable Integration ID. Delete creates a current impact preview across every environment connection, requires an interactive exact-name confirmation, and then permanently removes the Integration and its owned Seamward operational data. It rejects --yes, --force, piped input, and unattended execution.

Inspect observations and contracts

seamward observations list --integration <integration-id>seamward observations list --integration <integration-id> --limit 25 --cursor <next-cursor>seamward observations show <observation-id> --integration <integration-id>seamward contracts list --integration <integration-id>seamward contracts list --integration <integration-id> --limit 25 --cursor <next-cursor>seamward contracts status --integration <integration-id>seamward contracts validate <file>

Observation and contract reads use the active setup authorization and remain limited to its approved workspace environment. Their --integration argument is the selected environment's int_... connection ID printed by seamward integrations list. Contract validation reads only the named project file, validates OpenAPI 3.0/3.1 or JSON Schema draft 7/2020-12, and rejects paths outside the current project. List responses include nextCursor; pass it back unchanged to continue.

Diagnose the active connection

seamward statusseamward doctor

status reports the active workspace, environment, and Integration count. doctor performs the same authenticated context check and reports the local Node.js version.

Command options

Machine-readable output

Add --json to customer commands when their output is consumed by a script:

seamward whoami --jsonseamward integrations list --jsonseamward status --json

Successful JSON output is the same response object returned by Seamward. For example, an observation page includes observations, nextCursor, and pagination. A local validation returns:

{  "file": "contracts/orders.openapi.yaml",  "format": "openapi",  "valid": true}

Command failures exit with status 1. With --json, stderr contains:

{  "error": {    "code": "usage_error",    "message": "Actionable error message."  }}

Stable error codes include usage_error, authentication_required, validation_failed, scope_denied, not_found, network_error, request_failed, and command_failed. Invalid command syntax exits non-zero without changing local or remote state.

Authentication failures exit non-zero and direct the operator to seamward login. Unknown commands and missing required arguments also exit non-zero without changing local or remote state.

Advanced project commands

The command retains lower-level, review-first project operations for custom automation:

seamward discover .seamward project plan .seamward review .seamward verify .

These commands are read-only unless their help explicitly documents a write flag. Prefer seamward setup for the supported customer onboarding flow. The assisted setup command runs the exact setup engine version pinned by the installed CLI. Do not use the former seamward setup [directory] planner syntax; use seamward project plan [directory] for that advanced flow.

Next: follow Automatic setup, or resolve a failure with the Error reference.