quickstart.md

BeforeShip Quickstart

BeforeShip is a local launch gate for AI-built apps.

Install

From npm:

npx beforeship@latest scan

From this repository:

npm install
npx beforeship --version

First Scan

Scan the current project:

npx beforeship scan

Scan another project:

npx beforeship scan "C:\path\to\your-app"

Scan a public GitHub repository without cloning it:

npx beforeship scan-github owner/repo

Full GitHub URLs work too:

npx beforeship scan-github https://github.com/owner/repo

Use a specific branch or tag:

npx beforeship scan-github owner/repo --ref main

Create GitHub issues for the highest-priority findings:

GITHUB_TOKEN=ghp_your_token npx beforeship scan-github owner/repo --create-issues

Limit issue creation:

GITHUB_TOKEN=ghp_your_token npx beforeship scan-github owner/repo --create-issues --issue-limit 3

Use GITHUB_TOKEN for private repos, issue creation, and higher GitHub API rate limits.

Use JSON for automation:

npx beforeship scan --json --no-report

Reports

By default, reports are written into the scanned project:

.beforeship/
  launch-report.html
  launch-report.md
  findings.json
  fix-prompts.md
  loop-memory.json

Add .beforeship/ to .gitignore:

npx beforeship ignore

Fix Prompts

Print the highest-priority fix prompt:

npx beforeship fix-prompts

Print all prompts:

npx beforeship fix-prompts --all

Exit Codes

0  SHIP / command succeeded
1  tool error
2  launch gate blocked

Demo Fixture

npx beforeship scan examples/flawed-next-supabase-app --no-report

Expected verdict:

DO NOT SHIP