shift-cli create-app

Scaffold a new Shift-powered application project.

Usage

shift-cli create-app <name>

Common Flags

Flag	Description
-t, --type <type>	App type: api, web, or fullstack
-s, --services <list>	Comma-separated platform services to include
--all-services	Include all known platform services
-p, --palette <id>	Seed a palette design system such as shift-palette or material-3
-b, --blueprint <name>	Apply a blueprint archetype such as scheduling
--no-interactive	Skip prompts and use flags/defaults only
-d, --dir <path>	Parent directory for the generated project

Description

create-app bootstraps the local project and wires it into the platform:

• Project scaffold — package manifest, TypeScript config, starter source, .claude references, and service-specific boilerplate
• Yellow Pages registration — registers the app as a service in the catalog when requested
• Stage bootstrap — creates an initial Stage session and writes .shift/stage-app.config.json
• Palette seeding — optionally writes design tokens and Stage-friendly CSS tokens
• Browserless Stage API smoke scaffold — for api apps, adds a starter bun run test:stage contract
• Browser testing scaffold — for web and fullstack apps, adds Playwright config and delegated Stage E2E helpers
• Git bootstrap — when a GitHub provider is configured in Git and linked to Passport, creates or connects a private repository in the authenticated user's personal namespace and stores the canonical Git provider/repository ids on the app
• Claude session reporting — generates .claude/settings.json and .claude/hooks/report-event.ts so local Claude Code sessions can report prompts, tool calls, and stop events back to the platform Git service with SHIFT_AGENT_TOKEN
• Local-only fallback — if Git/Passport bootstrap is unavailable, still scaffolds the app locally and lets you connect a repo later

Generated Stage testing helpers include:

• tests/stage.ts
• tests/stage.smoke.test.ts
• playwright.config.ts
• e2e/stage.ts
• a starter E2E smoke test

The local .shift/stage-app.config.json file stores the current Stage session id, gateway URL, and any linked Stage app / repository metadata, including canonical Git provider/repository ids when available.

Examples

# Fullstack app with a palette
shift-cli create-app drive-hasher --type fullstack --palette material-3

# API-only app with explicit services
shift-cli create-app billing-sync --type api --services yp,stage,inference

# Non-interactive scaffold
shift-cli create-app trigger-app --type web --no-interactive

Prerequisites

• The gateway URL must be configured (see Configuration)
• You must be authenticated (see login)
• For automatic remote repo bootstrap, local git must be installed and a GitHub provider must be configured in Git with Passport-backed access for your account
• If the provider path is unavailable, create-app still succeeds as a local-only scaffold
• GitHub CLI (gh) is only used as a legacy fallback path when it is installed and authenticated