shipscreens

ShipScreens CLI

Best UX: treat screenshots as a build step. Keep the current Figma/Fastlane/manual screenshot workflow, tell your coding agent to ship release-safe screenshots, and let it inspect, plan, write a starter config when needed, capture connected device/emulator screens when no PNG folder exists, import existing screenshots when placeholders remain, build, verify, stage, and report via MCP or CLI. Use this package when app-dev CI or MCP-enabled agents need deterministic store-screenshot release ops that prevent Fastlane path churn, naming drift, and release-week rerun failures.

Tell your coding agent

Use ShipScreens as the build step for our mobile release screenshots. Keep our current design workflow, inspect this repo, choose workspace-local MCP if available otherwise CLI, capture current device/emulator screens if no screenshot folder exists, generate deterministic Fastlane-ready outputs, run verify/stage, and return a short report with output paths, warnings, and next steps. Only ask me if device or locale scope, panel #1 messaging, or store-upload approval is unclear.

Quickstart

npx --yes shipscreens@latest demo

Rendered mode (optional)

Rendered mode runs the UI renderer headlessly via Playwright Chromium. Install Chromium once per machine/CI runner:

npx playwright install --with-deps chromium

CI pipeline (copy/paste)

npx --yes shipscreens@latest inspect-release-context --json
npx --yes shipscreens@latest plan-release --json
npx --yes shipscreens@latest write-starter-config --profile appstore --json
npx --yes shipscreens@latest capture-screenshots --platform auto --out screenshots --slot 1 --profile appstore --json
npx --yes shipscreens@latest import-screenshots --from screenshots --profile appstore --json
npx --yes shipscreens@latest validate
npx --yes shipscreens@latest lock
npx --yes shipscreens@latest copy check --strict --write-pseudo-csv out/copy-pseudo.csv --write-report-json out/copy-check-report.json
npx --yes shipscreens@latest agent-run --out out --zip --stage --profile appstore --json

With --stage, agent-run writes out-stage, out/shipscreens.agent-report.json, and out/shipscreens.agent-summary.md by default.

Docs: https://shipscreens.com/tools/agent-cli/

MCP server (stdio)

npx --yes shipscreens@latest mcp serve

Fastest workspace bootstrap:

npx --yes shipscreens@latest mcp init --client cursor
# use claude | vscode | gemini for other clients

Claude Code local setup (.mcp.json)

{
  "mcpServers": {
    "shipscreens": {
      "command": "npx",
      "args": ["--yes", "shipscreens@latest", "mcp", "serve"]
    }
  }
}

Windows users can force npx through cmd /c:

{
  "mcpServers": {
    "shipscreens": {
      "command": "cmd",
      "args": ["/c", "npx", "--yes", "shipscreens@latest", "mcp", "serve"]
    }
  }
}

Cursor project setup (.cursor/mcp.json)

{
  "mcpServers": {
    "shipscreens": {
      "command": "npx",
      "args": ["--yes", "shipscreens@latest", "mcp", "serve"]
    }
  }
}

VS Code Copilot workspace setup (.vscode/mcp.json)

{
  "servers": {
    "shipscreens": {
      "type": "stdio",
      "command": "npx",
      "args": ["--yes", "shipscreens@latest", "mcp", "serve"]
    }
  }
}

Gemini CLI setup (.gemini/settings.json in project or ~/.gemini/settings.json):

{
  "mcpServers": {
    "shipscreens": {
      "command": "npx",
      "args": ["--yes", "shipscreens@latest", "mcp", "serve"]
    }
  }
}

OpenAI Responses API note

• Default tool_choice=auto lets the model decide whether to call tools.
• Use tool_choice=required when the workflow must force a ShipScreens tool call.