vk init

Usage

vk init [name] [options]

Arguments

Argument	Description
name	Project name (lowercase, hyphens allowed). If omitted, you’ll be prompted.

Options

Option	Description	Default
-t, --template <template>	Project template	api
-y, --yes	Skip interactive prompts	false
--local	Link local VentureKit packages (for development)	false

Templates

Template	Description	Includes
api	REST API with auth	Routes, health check, tasks CRUD
api+db	API with Postgres	+ Initial SQL migration, @venturekit/data
api+queue	API with SQS queue	+ Queue consumer, src/queues/
api+storage	API with S3 storage	+ Upload endpoint, @venturekit/storage
fullstack	Everything	Database + Storage + Queue

Examples

# Interactive (prompts for name and template)
vk init

# Named project with default template (api)
vk init my-app

# Specific template
vk init my-app --template api+db

# Non-interactive with defaults
vk init my-app --yes

# Use local VentureKit packages (for framework development)
vk init --local my-app

Generated Structure

api (default)

my-app/
├── config/
│   ├── base.ts            # Project identity (name, region)
│   ├── security.ts        # OAuth scopes and app clients
│   ├── dev.ts             # Dev environment (free preset)
│   └── prod.ts            # Production environment
├── src/
│   └── routes/
│       ├── health/get.ts  # GET /health (public)
│       └── tasks/
│           ├── get.ts     # GET /tasks (authenticated)
│           └── post.ts    # POST /tasks (authenticated)
├── tests/
├── vk.config.ts
├── package.json
├── tsconfig.json
└── .gitignore

api+db adds:

├── db/
│   └── migrations/
│       └── 0001_init.sql  # Initial pure-SQL migration
└── src/
    └── routes/...

Infrastructure: Postgres database pre-configured as a flat field on defineVenture() in vk.config.ts.

api+queue adds:

├── src/
│   ├── queues/
│   │   └── notifications.ts  # Queue consumer handler
│   └── routes/...

Infrastructure: SQS queue with DLQ pre-configured.

api+storage adds:

├── src/
│   └── routes/
│       ├── uploads/
│       │   └── post.ts    # POST /uploads (signed URL)
│       └── ...

Infrastructure: S3 bucket with CDN pre-configured.

Dependencies are installed automatically after scaffolding.

Naming Rules

Project names must:

• Start with a lowercase letter
• Contain only lowercase letters, numbers, and hyphens ([a-z][a-z0-9-]*)
• Be suitable for AWS resource naming

Next Steps

After creating the project:

cd my-app
vk dev