@venturekit/cli

Warning: This package is in active development and not production-ready. APIs may change without notice.

CLI for VentureKit — scaffolding, development, deployment, code generation, and database migrations.

Installation

npm install -g @venturekit/cli@dev

# Or use as a project dependency
npm install @venturekit/cli@dev

Commands

vk init [name]

Scaffold a new VentureKit project from a template.

vk init my-app
vk init my-app --template api
vk init my-app --template fullstack --yes

Templates:

• minimal — Basic API with health check (default)
• api — REST API with authentication and scoped endpoints
• fullstack — API + database + storage

vk dev

Start a local development server. Serves routes via HTTP with Docker services for infrastructure.

vk dev
vk dev --stage dev
vk dev --stage test --port 4099 --no-watch --no-crons   # E2E / CI stack

Flags:

• -s, --stage <stage> — stage name (default local). Also selects the stage-scoped local database (<databases[].name>_<stage>), cognito-local pool and storage bucket.
• -p, --port <port> — port to listen on (default 3000).
• --no-watch — disable file watching / hot reload.
• --no-crons — do not run scheduled tasks on their schedule. Handlers are still discovered and invokable via POST /_dev/invoke/cron/{name}, which is what test suites should use: a background sweep otherwise writes to the database your assertions read, competes with them for the single-process dev server, and spends provider quota on every tick.

Declared schedules run locally on their real cadence ({ rate: '1 hour' }, { cron: '0 3 * * ? *' }, 5- or 6-field), clamped to a 10s floor; enabled: false schedules never start.

vk deploy

Deploy your project to AWS via CDK. Supports stage-based deployments.

vk deploy
vk deploy --stage prod

vk remove

Tear down deployed AWS resources for a given stage.

vk remove
vk remove --stage stage
vk remove --stage prod --yes   # Skip confirmation

vk generate (alias: vk g)

Generate routes and environment configs.

# Generate a route handler
vk g route tasks                              # GET /tasks
vk g route tasks -m post                      # POST /tasks
vk g route tasks -m post --scopes tasks.write # POST /tasks (authenticated)
vk g route tasks/[id] -m delete               # DELETE /tasks/{id}

# Generate an environment config
vk g config staging

# Scaffold an end-to-end suite (Playwright + @venturekit/testing)
vk g e2e                          # Reads vk.config.ts for the database + auth wiring
vk g e2e --port 4100 --stage e2e  # Isolated port / stage
vk g e2e --filter @acme/api       # Monorepo: where vk.config.ts lives

vk g e2e writes playwright.config.ts and an e2e/ directory, patches package.json (a test:e2e script + devDependencies) and .gitignore, and skips any file that already exists unless you pass --force.

The generated config delegates its webServer block to vkWebServers() from @venturekit/testing/playwright, which creates the stage database, migrates and seeds it, then boots vk dev with crons disabled — in that order. Each of those is load-bearing:

• Nothing else creates the database (vk migrate and vk dev both assume it exists), and Playwright runs webServer entries before globalSetup, so creation has to be part of the command.
• vk dev derives <database>_<stage> from vk.config.ts and ignores an inherited DATABASE_URL, so the scaffold reads the declared name from your config rather than guessing. Get it wrong and you migrate one database while the API serves another, empty one.
• Crons share the dev server with the requests under test, write to the rows specs assert on, and can spend real provider quota on every tick.

Role login (e2e/roles.setup.ts) is only generated when the project declares an auth intent; the database steps only when it declares a database.

vk migrate

Apply pending pure-SQL migrations from db/migrations/. Tracked in the __vk_migrations table; already-applied files are skipped.

vk migrate                       # Apply pending schema migrations
vk migrate --seed                # Apply migrations, then pending seeds from db/seeds/
vk migrate --env prod            # Target a specific environment
vk migrate status                # Show which migrations and seeds have been applied

vk cert request

Request an ACM certificate for a custom domain and, when DNS-validated, writes the certificate ARN straight into your config/*.ts file. The validation records are printed in a Cloudflare-friendly table so you paste them into your DNS provider and keep moving.

# Primary domain only, wait for ISSUED, auto-write ARN to config.
vk cert request --domain api.example.com

# With SANs; non-blocking (print and exit without waiting).
vk cert request --domain preview.api.example.com \
                --san api.example.com \
                --no-wait

# Force the ARN into a specific config file instead of auto-detecting.
vk cert request --domain api.example.com --write config/prod.ts

Re-running the command is safe: it reuses any existing PENDING_VALIDATION / ISSUED certificate that covers the same name set, so a flaky network or partial Cloudflare edit can be recovered by just running the command again.

vk gha bootstrap

Create the GitHub OIDC provider and IAM deploy role your CI workflow needs, scoped to this repository and the stages declared in vk.config.ts. Outputs the role ARN for the AWS_DEPLOY_ROLE_ARN GitHub secret.

# Auto-detect repo from `git remote` and stages from vk.config.ts.
vk gha bootstrap

# Override if needed.
vk gha bootstrap --repo my-org/my-repo --stages preview,prod

# Tight inline policy instead of AdministratorAccess.
vk gha bootstrap --scoped

Idempotent — re-running refreshes the trust policy and swaps the attached policy between AdministratorAccess (default) and the VentureKit-maintained scoped policy (--scoped) without leaving orphan attachments.

vk gha workflow

Generate .github/workflows/deploy.yml from vk.config.ts. Maps branches to stages based on your envs declarations, with main routed to the prod stage by default.

# Identity mapping for non-prod stages + main→prod.
vk gha workflow

# Explicit branch → stage overrides (repeatable).
vk gha workflow --branch dev=preview --branch main=prod --force

Emits a workflow that uses OIDC federation (no long-lived AWS keys), serializes deploys per stage, and calls vk deploy --stage <stage>.

Project Structure

After vk init, your project looks like:

my-app/
├── config/
│   ├── base.ts        # Project identity (name, region)
│   ├── security.ts    # OAuth scopes and app clients
│   ├── dev.ts         # Dev environment settings
│   ├── stage.ts       # Staging environment settings
│   └── prod.ts        # Production environment settings
├── src/
│   └── routes/        # File-based routing
│       └── health/
│           └── get.ts # GET /health
├── vk.config.ts
├── package.json
└── tsconfig.json

API Reference

See the CLI reference for full command documentation.

License

Apache-2.0 — see LICENSE for details.