Product CLI

The shipfoundry CLI operates the Developer API from your terminal (Node 22 or newer, or Bun).

Availability

Install the public package with Node.js 22 or newer:

npm install -g @shipfoundry/cli@0.1.0
shipfoundry --help

The command is shipfoundry. It works without the ShipFoundry application source tree.

Configure

Sign in to your ShipFoundry instance and open /dashboard/settings/mcp. Under Developer Keys, create a key with access to the projects and permissions your client needs. Copy the secret once and keep it private. shipfoundry auth login prints these setup instructions even before a base URL is configured.

export SHIPFOUNDRY_BASE_URL=https://shipfoundry.ai
export SHIPFOUNDRY_API_KEY="<developer-key>"

Precedence is explicit option, environment, then non-secret profile. A base URL is required; there is no default production destination. Plain HTTP is allowed only for loopback development endpoints. shipfoundry auth login explains the dashboard bootstrap path; the CLI never mints keys and never persists secrets.

Set up a project

Start with shipfoundry projects list --json. Reuse the intended project when it exists; use shipfoundry projects create --help for creation options. See the API guide for the context JSON fields and the agent setup guide for consent and readiness steps.

shipfoundry projects context "$PROJECT_ID" --json
shipfoundry projects context "$PROJECT_ID" --file context.json \
  --idempotency-key "$CONTEXT_REQUEST_KEY" --yes --json
shipfoundry repositories list --project "$PROJECT_ID" --json
shipfoundry repositories select "$REPOSITORY_ID" --project "$PROJECT_ID" \
  --idempotency-key "$REPOSITORY_REQUEST_KEY" --yes --json
shipfoundry watchlist list --project "$PROJECT_ID" --json
shipfoundry projects status "$PROJECT_ID" --json

Repository consent happens in the browser. Select an ID returned by repositories list. Inspect watchlist add --help and add relevant returned suggestions before activation. When readiness checks pass and the owner approves starting a first review:

shipfoundry projects activate "$PROJECT_ID" \
  --idempotency-key "$ACTIVATION_REQUEST_KEY" --yes --json
shipfoundry reviews status "$PROJECT_ID" --json

Activation can consume the plan's allowance. Inspect the dispatch result, then poll reviews status with a deadline. An accepted request does not mean the review has completed. Repository disconnection is also available through repositories disconnect; it requires the project-repository selection ID returned by the service and explicit --yes.

Run the workflow

shipfoundry doctor --json
shipfoundry projects list --json
shipfoundry projects status "$PROJECT_ID" --json
shipfoundry updates list --project "$PROJECT_ID" --workspace active --json
shipfoundry updates list --project "$PROJECT_ID" --workspace needs_input --json
shipfoundry updates show "$UPDATE_ID" --json
shipfoundry briefs show "$UPDATE_ID" --json
shipfoundry briefs request "$UPDATE_ID" \
  --mode if_missing_or_stale --idempotency-key "$REQUEST_KEY" --yes --json
shipfoundry operations wait "$OPERATION_ID" --timeout 120 --json
shipfoundry handoff show "$UPDATE_ID" --format markdown > handoff.md

shipfoundry outcomes record "$UPDATE_ID" \
  --file outcome.json --idempotency-key "$OUTCOME_REQUEST_KEY" --yes --json

Example outcome.json:

{
  "outcome": "investigated",
  "summary": "Inspected the checkout flow and confirmed the proposed change needs further testing.",
  "filesInspected": ["src/app/checkout.ts"],
  "validationNotes": [
    "Ran the checkout tests; no implementation change was made."
  ]
}

Automation rules

• --json emits structured data on stdout; diagnostics go to stderr.
• Reads never prompt. Every write requires --yes; nothing hangs on a TTY prompt.
• --wait stops at its timeout. On timeout the operation ID is reported so another process can resume with operations show or operations wait.
• Preserve --idempotency-key across retries; a new key per retry can duplicate paid work.
• Exit codes: 0 ok, 2 usage, 3 auth, 4 forbidden, 5 not found, 6 conflict, 7 quota, 8 transient, 9 wait timeout.

Related guides

• Set Up With Your Agent
• API Authentication And Retries
• MCP

Request Missing Coverage

shipfoundry stack request --project <project-id> --name "<missing-tool>" \
  --note "How this repository uses it" \
  --idempotency-key request-missing-tool-01 --yes --json
shipfoundry watchlist list --project <project-id> --json

Use this after stack resolve reports a missing item. The request does not activate tracking or start paid work. Keep the returned request ID and check requests in the watchlist response for coverage status.

To retry a failed first review after its cause is fixed, use shipfoundry projects activate <project-id> --retry --yes with a new --idempotency-key. Poll shipfoundry reviews status <project-id> afterward.