@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 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

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.