ostup

Scaffold a new client project with one command. Get a live GitHub repo and live Vercel deploy URL in under ten minutes, even from a stock computer.

What this does

When you run this tool, it will:

1. Ask you a few questions about the project
2. Create a folder on your machine with a Next.js starter site
3. Create a private GitHub repository for the project
4. Deploy the site to Vercel and give you a live URL
5. Set up institutional memory files (CLAUDE.md, AGENTS.md) so any CLI agent (Claude Code, Codex, Gemini CLI) knows your project rules
6. Create an inputs/ folder inside the project where you can drop any prior materials (research, reference repos, screenshots, brand assets) you want the agent to have on hand
7. If you ran ostup brief first (recommended), drop in working code for your profile. The four industry profiles ship real Next.js overlays: lead-gen (hero + services + contact form + Resend wiring), booking (booking form + dates + email confirmation), saas-dashboard (Better Auth + guarded dashboard + settings), blog (MDX posts + RSS
   • sitemap). Your first deploy shows a working homepage and day-one flow, not a blank Next.js welcome.
8. Optionally pass --private to ship an app-level default-deny project on Vercel Hobby: middleware blocks every request except sign-in/up + audit-health, blob helpers default to access: 'private', image optimizer cannot proxy external URLs, rate limiting and audit logging are wired. Run ostup doctor --privacy <url> after deploy to verify. Toggle on/off an existing project with ostup private add / ostup private remove (manifest at .ostup/private.json makes the remove cleanly revertable).
9. Optionally pass --auth=clerk or --auth=google to wire a working login flow into the scaffold. Clerk uses @clerk/nextjs (hosted UI, free up to 10k MAU); Google uses NextAuth v5 with the Google provider (free; you create the OAuth app on Google Cloud). Both ship sign-in / sign-up pages out of the box. --auth composes cleanly with --private (the default-deny middleware recognizes both providers' session cookies).
10. Optionally pass --publish-ready if this CLI will be used to publish an npm package later. ostup walks you through getting an npm Bypass-2FA token (browser flow or guided token paste) and saves it to ~/.npmrc. After that, the /publish slash command lets your agent ship a new version with one command.

Quick Start

Pick the path that matches your computer.

Developer default (you already have Node and npm)

Use npx first. It runs the current package without a global install:

npx @oaklandzoo/ostup@latest init

ostup will detect any missing tools (git, gh, vercel) and offer to install them. Pass --skip-bootstrap to bypass detection or --no-install to see what would be installed without making changes.

Mac (beginner — stock computer with nothing installed)

Open Terminal and paste:

/bin/bash -c "$(curl -fsSL https://ostup-install.vercel.app/install.sh)"

That script installs Homebrew and Node (if missing), then runs ostup init, which installs Git, GitHub CLI, and Vercel CLI and walks you through signing in. Total time: about 5-10 minutes the first time, mostly download waits.

Inspect-first path:

curl -fsSL https://ostup-install.vercel.app/install.sh -o install-ostup.sh
less install-ostup.sh
/bin/bash install-ostup.sh

To pre-set flags (advanced):

/bin/bash -c "$(curl -fsSL https://ostup-install.vercel.app/install.sh)" -- --yes --profile=default

Windows (beginner — stock computer with nothing installed)

Open PowerShell and paste:

irm https://ostup-install.vercel.app/install.ps1 | iex

That script installs Node via WinGet (if missing), then runs ostup init, which installs Git, GitHub CLI, and Vercel CLI and walks you through signing in. Total time: about 5-10 minutes the first time.

To pre-set flags (advanced):

irm https://ostup-install.vercel.app/install.ps1 -OutFile install.ps1
./install.ps1 --yes --profile=default

If you'd rather install it globally so the command is just ostup:

npm install -g @oaklandzoo/ostup
ostup init

What ostup needs (handled for you by the beginner installer)

The beginner installer scripts above handle this list automatically. This is what they're installing under the hood:

• Node.js 20+
• Git
• GitHub CLI (gh)
• Vercel CLI (vercel)
• A free GitHub account (https://github.com/signup) — sign in during the flow
• A free Vercel account (https://vercel.com/signup) — sign in during the flow

If you do not have GitHub or Vercel accounts yet, the tool pauses and walks you through creating them when you reach those steps.

Alternate: install from source

If you cloned https://github.com/DubsFan/ostup and want to run from your local checkout:

cd /path/to/ostup
npm install
npm link
ostup --version

Use

In Terminal, navigate to the parent folder where you want the new project to be created:

cd ~/Projects

Then run:

npx @oaklandzoo/ostup@latest init

The tool will ask you a series of questions. Answer each one. When the tool finishes, you will see a live deploy URL and an OSTUP Cockpit path. Open the cockpit path to see what was created, what is ready, what is missing, and the next safest command.

If you installed ostup globally, ostup init is equivalent.

Use (retrofit an existing repo)

If you already have a repo (any language: Next.js, Python, Rails, static, etc.) and want to add the ostup agent kit to it without re-creating the project, run from inside that repo:

npx @oaklandzoo/ostup@latest adopt

This installs CLAUDE.md, AGENTS.md, the docs/ status doc set, all 21 slash commands under .claude/commands/, the scripts/screenshot.sh and scripts/verify.sh helpers, and an inputs/ skeleton. Non-destructive by default:

• Existing CLAUDE.md and AGENTS.md get an ostup managed block appended at the END (your rules win on conflict).
• Existing .gitignore keeps every line you had plus any ostup entries it was missing.
• Existing slash commands and scripts of the same name are preserved untouched.
• HANDOFF.md is never written. Run /prompt-start or /bootstrap next.
• Re-runs are bit-for-bit idempotent: nothing changes on a second run.

adopt also accepts the same overlay flags as init (--auth=clerk|google, --private, --brand-pack <name>, --white-label, --profile <name>). Next.js-only overlays warn-and-skip on non-Next.js repos. Use --dry-run to see the plan before writing.

OSTUP Cockpit

ostup cockpit generates a local status dashboard and redacted JSON report:

npx @oaklandzoo/ostup@latest cockpit --no-open

Default output:

• .ostup/cockpit/index.html
• .ostup/cockpit/status.json

The cockpit checks local evidence only: package manager, framework, Git state, Vercel link metadata, env key names, agent files, README/changelog, test/build scripts, readiness scores, and next steps. Secret values are not written.

Useful options:

ostup cockpit --json
ostup cockpit --workspace --refresh --no-open
ostup cockpit --dry-run
ostup cockpit --out ./tmp/cockpit --no-open
ostup cockpit --refresh --no-open

Existing cockpit files are kept unless you pass --refresh.

Workspace cockpit:

• ostup cockpit --workspace --refresh --no-open
• Reads ~/.ostup/workspaces.json.
• Writes ~/.ostup/cockpit/index.html.
• Writes ~/.ostup/cockpit/workspaces.json.
• Shows repo tabs and filters for all, active, dirty, needs-env, and ready.
• Connects local tool context from repo files: .vscode, .cursor, AGENTS.md, .codex, CLAUDE.md, and .claude.

Generated sample:

• Run ostup cockpit --refresh --no-open.
• Open .ostup/cockpit/index.html.
• Review .ostup/cockpit/status.json.

Product docs:

• docs/product/ostup-cockpit.md
• docs/product/ostup-cockpit-stories.md
• docs/product/ostup-cockpit-tasks.md

AGENTS.md is a complete manual

AGENTS.md is the cross-vendor standard read by Codex, Cursor, Gemini CLI, and others. It ships the entire operating manual: hard rules, reply format, error protocol, visual verification, workflow, plus a command and CLI index. CLAUDE.md is the Claude-voiced copy of the same rules. A parity test (test/agents-parity.test.mjs) keeps their PART structure in lockstep, so an agent reading only AGENTS.md is never working from a weaker manual. Privacy mode (--private) writes its rules to both files.

Older repos still carrying a thin AGENTS.md stub: re-run adopt to upgrade. Your customized files are preserved (sidecar), so this is safe.

Customized manuals are never clobbered

If your repo already has a hand-written CLAUDE.md or AGENTS.md, adopt leaves it 100% untouched and writes the fresh template to a sidecar (CLAUDE.ostup-new.md) so you can diff and copy in anything you want. It detects "customized" when the file has content outside the ostup markers or a different number of # PART sections than the template. Re-running adopt never grows your manual or duplicates a section.

• Want the kit's new sections folded straight into your manual instead of a sidecar? Pass --merge-manual: adopt inserts only the # PARTs your manual lacks (matched by number, renames tolerated), never rewriting your existing sections. Idempotent.

Profile-aware install

adopt detects your repo type (node-web / python / static / generic) and installs accordingly:

• A Python or static repo does NOT get web-only slash commands (/add-auth, /generate-image, /publish, ...) or web .gitignore lines (.next/, node_modules/). It gets the core workflow commands and language-appropriate ignores. Pass --all-commands to install every command regardless.

Advanced: manage an existing project

After adopt runs, you can turn individual features on or off at any time. Each command below is copy-paste ready from inside your project folder.

Lock down access (private mode)

ostup private add

Wires default-deny middleware, rate limiting, and audit logging into your Next.js app. Every route returns 401 until a signed-in user hits it. Run ostup private status to confirm, or ostup private remove to undo.

Install and activate the agent-gate guardrail

ostup guard add       # install in preview (watch-only) mode
ostup guard activate  # turn on enforcement so risky AI actions are blocked

Requires uv on your PATH before you run these. Install it once with brew install uv. Preview mode is safe and watch-only. Run activate only when you are ready for live blocking.

Manage session hooks

ostup hooks add blocker-radar

Adds a specific session hook (here: the blocker-radar helper that surfaces stuck to-dos at session end). Run ostup hooks list to see all available hooks and which are wired in.

Dial model cost

ostup model set-default sonnet

Sets the everyday model tier to sonnet. Options are haiku (cheapest), sonnet (default), or opus (strongest). Writes .ostup/model-policy.json. Delete that file to reset to defaults.

List past scaffolds

ostup workspaces ls

Prints every project ostup has scaffolded or adopted on this machine, with the path and timestamp. Read-only.

Save a reusable brand

ostup brand-pack add my-brand

Snapshots the current brand files (colors, fonts, logo paths) under the name my-brand so you can apply them to a future project with --brand-pack my-brand.

Bundle for client handoff

ostup export-pro --output handoff.zip

Gathers the brief, brand pack, content files, and initial PRD into one ZIP. Skips any file that does not exist yet. Add --dry-run to see the list before writing.

Verify a deployed app is locked down

ostup doctor --privacy --url https://my-app.vercel.app

Probes the live URL for default-deny enforcement. Read-only. Exits non-zero if any route responds with 200 when it should be blocked.

Troubleshooting (headless / CI / Docker)

These gotchas come up when ostup runs without a browser or without an interactive terminal. Each entry names the prerequisite before describing the workaround.

GitHub and Vercel auth in headless environments

Prerequisite: a GH_TOKEN (GitHub personal access token) and a VERCEL_TOKEN (from vercel.com/account/tokens).

Browser-based gh auth login and vercel login do not work in CI or Docker. Set these two tokens in your environment (or in a .env file at the repo root) before running ostup:

GH_TOKEN=ghp_...
VERCEL_TOKEN=...

ostup reads them automatically via loadDotEnv() at startup.

npm publish in CI (--publish-ready flag)

Prerequisite: an npm access token with publish rights, and write access to ~/.npmrc on the runner.

npm login requires a TTY and a browser. In CI, skip the interactive flow: paste //registry.npmjs.org/:_authToken=<your-token> directly into ~/.npmrc on the runner before ostup runs.

agent-gate guardrail (ostup guard add)

Prerequisite: uv must be installed and on your PATH before running ostup guard add.

The guardrail installs its Python package via uv. Without it the command exits with an error. Install once:

brew install uv          # macOS
pip install uv           # Linux / Docker (if pip is available)

Visual checks (scripts/screenshot.sh)

Prerequisite: Chrome or Chromium must be on your PATH.

scripts/screenshot.sh drives headless Chrome for visual verification. On a fresh Linux runner or Docker image, install it before running the script:

apt-get install -y chromium-browser   # Debian/Ubuntu
# or set PUPPETEER_EXECUTABLE_PATH to an existing Chrome binary

Private mode returns 401 on first deploy

This is expected behavior, not a break.

After ostup private add and a fresh deploy, every route returns 401 until you sign in through the auth flow at least once. The middleware is working correctly. Open the app in a browser, sign in, and the 401 clears for that session.

Use (operator brief mode, recommended for real projects)

If you want the agent to start with a richer context (business goal, audience, business model, day-one flows, brand, constraints), run the 10-question intake first:

ostup brief

That writes docs/brief.md, docs/brief.json, and tasks/prd-initial-build.md in the current folder. Then scaffold the project with the brief:

ostup init --brief ./docs/brief.json

The tool classifies one of 8 site profiles (marketing, lead-gen, booking, blog, storefront, saas-dashboard, directory, portfolio), picks the right add-ons (auth, payments, email, postgres, mdx, blob, analytics), and applies a profile-specific overlay so the agent has a clear day-one plan.

Questions the tool will ask

| Question | What to answer | |---|---| | Project name | A short kebab-case name like client-name or widget-shop | | Display name | The human readable version, like "Client Name" | | Description | One sentence, 10 to 200 characters | | Profile | Press Enter to accept goodshin | | Stack | Press Enter to accept next. Other options: static, local, none (see Stacks below) | | Visibility | Press Enter to accept private | | GitHub owner | Press Enter to accept your GitHub username | | Vercel scope | Press Enter to accept your Vercel scope | | Prior materials? | Answer y if you have prior materials to bring in. A single file or a whole folder both work. The tool copies them into inputs/. Answer n to skip; you can drop files into inputs/ later. |

If the tool detects you are not logged in to GitHub or Vercel, it will print step-by-step instructions and pause until you finish.

Stacks

The Stack question controls what app skeleton ostup writes:

| Stack | What it is | Deploys to Vercel? | |---|---|---| | next | Next.js + Tailwind web app (default) | Yes | | static | A single index.html | Yes | | local | A local-first dashboard: HTML UI plus a tiny zero-dependency Node server, with optional AI and Google Sheets. Runs on your machine with npm run dev. Your data stays in ./data/ and is gitignored. | No | | none | No app code | No |

Pick local for private, single-user tools (a tax-intake helper, a personal tracker) where the data is sensitive and you do not want a public URL. It needs no Vercel account. GitHub is optional and only ever holds the code, never your data.

What you get when it finishes

• A local folder at ./<project-name> with the Next.js site code
• A private repo at https://github.com/<your-username>/<project-name>
• A live deploy at a *.vercel.app URL
• CLAUDE.md, AGENTS.md, README.md inside the project, filled in with your project details
• An inputs/ folder for any operator-supplied materials, with a README explaining what goes where

The local stack is different: there is no *.vercel.app URL. Instead you get a dashboard you run with npm run dev and open at http://localhost:4321, with your data saved locally under ./data/.

What to do next

Open the new folder in your editor and start working. To use a CLI agent:

cd <project-name>
claude

Or replace claude with codex, gemini, or your preferred agent. The CLAUDE.md and AGENTS.md files tell the agent your conventions so you do not have to repeat them every session.

Troubleshooting

| Problem | Fix | |---|---| | "command not found" for node/gh/vercel | Run the beginner installer for your OS (top of this README). Or run ostup bootstrap if you already have Node. | | "gh auth required" | Re-run ostup init and pick "Sign in to GitHub in your browser". Or run gh auth login. | | "vercel auth required" | Re-run ostup init and pick "Sign in to Vercel in your browser". Or run vercel login. | | "Project name invalid" | Use only lowercase letters, numbers, and hyphens | | "Repo already exists" | Pick a different project name | | Vercel deploy hangs more than 5 minutes | Cancel with Ctrl-C, run again | | Deploy URL returns 401 | The tool tried to auto-disable Vercel deployment protection but could not. Open Vercel dashboard, find your project, Settings, Deployment Protection, Disable. | | "ingest path not found" | The path you gave does not exist. Re-run and provide a valid absolute or relative path. | | Beginner installer failed | The bash and PowerShell installers log to ~/.ostup/logs/install-*.log. The ostup CLI logs to ~/.ostup/logs/init-*.log. Open the most recent log for the failing command's stderr. | | "BOOTSTRAP_FAILED: Homebrew missing" | You ran npx @oaklandzoo/ostup@latest init on a Mac without Homebrew. Run the Mac beginner installer at the top of this README instead. | | "BOOTSTRAP_FAILED: WinGet missing" | Update App Installer from the Microsoft Store: ms-windows-store://pdp/?productid=9NBLGGH4NNS1. | | "/opt/homebrew/Cellar is not writable" | You are on a shared Mac where Homebrew was installed by another user. Current ostup routes around this by installing gh to ~/.local/bin/ and routing vercel through ~/.npm-global/. If you saw this error, upgrade with npx @oaklandzoo/ostup@latest update. |

Advanced: API tokens instead of interactive login

If you want to use API tokens (for CI, automation, or to avoid the browser login flow), copy .env.example to .env and fill in your tokens. The tool reads credentials in this order:

1. Environment variables (GH_TOKEN, VERCEL_TOKEN)
2. .env file in the current directory
3. Interactive CLI auth from gh and vercel

Any one of those is enough. Never commit your .env to git.

For full automation including automatic disable of Vercel deployment protection on team accounts, set VERCEL_TOKEN in your environment or .env. Without it, the tool falls back to reading the Vercel CLI auth file on macOS at ~/Library/Application Support/com.vercel.cli/auth.json. On a fresh machine where you have not run vercel login yet, that file will not exist, so VERCEL_TOKEN is the reliable path. Get a token at https://vercel.com/account/tokens.

Advanced: bring materials in non-interactively

Pass --ingest <path> to copy a folder of operator-supplied materials into the new project's inputs/ folder without being prompted:

npx ostup init --yes --name my-app --ingest ~/Desktop/client-handoff

The tool recursively copies the contents and writes inputs/INGEST_MANIFEST.md listing what was brought in.

Support

This tool is maintained at https://github.com/DubsFan/ostup Open an issue there if you hit a bug or need help.