CLI Reference

Comprehensive reference for all SwallowKit CLI commands and options.

swallowkit init
swallowkit machine
swallowkit-mcp
swallowkit create-model
swallowkit add-connector
swallowkit add-auth
swallowkit dev
swallowkit scaffold
swallowkit create-dev-seeds
swallowkit provision

swallowkit machine

Machine-readable command group for AI / MCP integrations.

Usage

bash

npx swallowkit machine <command> <subcommand> [options]

Available commands

Command	Purpose
`inspect project`	Return framework-owned project metadata
`inspect entities`	Return entity and schema metadata
`inspect routes`	Return BFF / Functions route metadata
`validate project`	Return structured validation violations
`generate model`	Run `create-model` in non-interactive JSON mode
`generate scaffold`	Run `scaffold` in non-interactive JSON mode

Examples

bash

npx swallowkit machine inspect project
npx swallowkit machine validate project
npx swallowkit machine generate model todo --overwrite never
npx swallowkit machine generate scaffold todo --api-only

Output contract

stdout is always a single JSON document
commands are non-interactive
success and failure are both structured
generate model requires an explicit overwrite policy (always or never)

See the AI / MCP Guide for architecture details and response examples.

swallowkit-mcp

Bundled MCP stdio server for AI coding agents.

Usage

bash

npx swallowkit-mcp

Exposed MCP tools

swallowkit_inspect_project
swallowkit_inspect_entities
swallowkit_inspect_routes
swallowkit_validate_project
swallowkit_generate_model
swallowkit_scaffold_model

The MCP server is a thin adapter over swallowkit machine ... and does not introduce framework logic of its own.

swallowkit init

Initialize a new SwallowKit project.

Usage

bash

npx swallowkit init [project-name] [options]
# or
pnpm dlx swallowkit init [project-name] [options]

Arguments

project-name (optional): Project name. Initializes in current directory if omitted

Options

Option	Description	Values	Default
`--template <template>`	Template to use	`default`	`default`
`--next-version <version>`	Next.js version	e.g. `16.0.7`, `latest`	`latest`
`--cicd <provider>`	CI/CD provider	`github`, `azure`, `skip`	(prompt)
`--backend-language <language>`	Azure Functions backend language	`typescript`, `csharp`, `python`	(prompt)
`--cosmos-db-mode <mode>`	Cosmos DB mode	`freetier`, `serverless`	(prompt)
`--vnet <option>`	Network security	`outbound`, `none`	(prompt)

Interactive vs Non-Interactive Mode

By default, init asks interactive prompts for CI/CD, Azure Functions backend language, Cosmos DB mode, and network settings.

You can skip prompts by passing flags directly:

bash

# Fully non-interactive
npx swallowkit init my-app --cicd github --backend-language csharp --cosmos-db-mode serverless --vnet outbound

# Partially non-interactive (only --cicd specified; the rest will prompt)
npx swallowkit init my-app --cicd skip

This is especially useful when calling the CLI from VS Code extensions or scripts where stdin is not a TTY.

Invalid flag values produce a clear error:

❌ Invalid --cicd value: "invalid". Must be: github, azure, skip

Interactive Prompts

When flags are not specified, the following prompts are shown:

CI/CD Provider: GitHub Actions, Azure Pipelines, or Skip
Backend Language: TypeScript, C#, or Python
Cosmos DB Mode: Free Tier or Serverless
Network Security: VNet Integration or None

Backend Language Notes

typescript: Functions consume the shared Zod package directly.
csharp / python: swallowkit scaffold exports OpenAPI into functions/openapi/ and generates native backend schema assets into functions/generated/.

Generated Files

my-app/
├── app/                      # Next.js App Router
│   ├── api/greet/            # BFF sample
│   ├── layout.tsx
│   └── page.tsx
├── components/               # React components
├── lib/
│   ├── api/backend.ts        # BFF client (api.get/post/put/delete)
│   ├── database/             # Cosmos DB client (optional)
│   │   ├── client.ts         # CosmosClient
│   │   └── repository.ts     # Repository pattern
│   ├── models/               # Data models
│   └── schemas/              # Zod schemas
├── functions/                # Azure Functions
│   ├── src/                  # TypeScript handlers
│   ├── Crud/                 # C# handlers
│   ├── blueprints/           # Python handlers
│   ├── generated/            # Native-generated schema assets for C#/Python
│   ├── openapi/              # Exported OpenAPI specs for C#/Python
│   ├── host.json
│   └── local.settings.json
├── infra/                    # Bicep IaC
│   ├── main.bicep
│   ├── main.parameters.json
│   └── modules/
│       ├── staticwebapp.bicep
│       ├── functions.bicep
│       └── cosmosdb.bicep
├── .github/workflows/        # CI/CD (GitHub Actions)
│   ├── static-web-app.yml
│   └── azure-functions.yml
├── .github/
│   ├── copilot-instructions.md   # GitHub Copilot instructions
│   └── instructions/             # Copilot layer-specific rules
│       ├── shared-models.instructions.md
│       ├── bff-routes.instructions.md
│       └── azure-functions.instructions.md
├── .env.local                # Environment variables
├── .env.example
├── next.config.js
├── swallowkit.config.js
├── staticwebapp.config.json
├── .mcp.json                # Project-scoped MCP bootstrap using local installed SwallowKit
├── AGENTS.md                 # Coding agent instructions (Codex)
├── CLAUDE.md                 # Claude Code instructions
└── package.json

AI Agent Bootstrap Files

The init command automatically generates instruction files for multiple AI coding agents, plus a project-scoped MCP bootstrap for runtimes that support repository MCP discovery. Together, these files help AI agents (GitHub Copilot, Claude Code, OpenAI Codex, etc.) follow the project's architecture and conventions when generating or modifying code.

Generated Files

File	Target Agent	Description
`AGENTS.md`	OpenAI Codex / generic agents	Full architecture spec, conventions, naming rules, CLI skills
`CLAUDE.md`	Claude Code	Quick reference + CLI commands (references `AGENTS.md` for full spec)
`.mcp.json`	Claude Code / project MCP runtimes	Project-scoped launcher for the locally installed `swallowkit-mcp` entrypoint
`.github/copilot-instructions.md`	GitHub Copilot	Summary of key rules (auto-loaded by Copilot)
`.github/instructions/shared-models.instructions.md`	GitHub Copilot	Layer-specific rules for `shared/models/**`
`.github/instructions/bff-routes.instructions.md`	GitHub Copilot	Layer-specific rules for `app/api/**`
`.github/instructions/azure-functions.instructions.md`	GitHub Copilot	Layer-specific rules for `functions/**`

The full content of the generated AGENTS.md is shown below:

markdown

# AGENTS.md

This project was generated by **SwallowKit**.
All coding agents **must** follow the architecture and conventions described below.

## Architecture Overview

This is a full-stack TypeScript application deployed on Azure with the following layers:

```
Frontend (React / Next.js App Router)
  ↓ fetch('/api/{model}', ...)
BFF Layer (Next.js API Routes)
  ↓ HTTP → Azure Functions
Backend (Azure Functions with Cosmos DB bindings)
  ↓
Azure Cosmos DB (Document Database)
```

### Project Structure

```
my-app/
├── app/                    # Next.js App Router
│   ├── api/               # BFF API routes (proxy to Azure Functions)
│   └── {model}/           # UI pages per model (list, detail, create, edit)
├── functions/             # Azure Functions (backend)
│   └── src/               # HTTP trigger handlers with Cosmos DB bindings
├── shared/                # Shared workspace package
│   ├── models/            # Zod schema definitions (single source of truth)
│   └── index.ts           # Re-exports all models
├── lib/
│   └── api/               # API client utilities (backend.ts, call-function.ts)
├── components/            # Shared React components
├── infra/                 # Bicep infrastructure-as-code files
│   ├── main.bicep
│   └── modules/
├── .mcp.json              # Project-scoped MCP bootstrap using local installed SwallowKit
└── .github/workflows/     # CI/CD workflows (if configured)
```

## SwallowKit MCP / Machine Workflow
<!-- SwallowKit MCP / Machine ワークフロー -->

- This repository includes a project-scoped `.mcp.json` file that starts the locally installed SwallowKit MCP server on runtimes that auto-load project MCP configurations.
- Prefer the `swallowkit_*` MCP tools for framework-owned inspection, validation, and generation when they are available.
- If MCP is unavailable in your runtime, fall back to the machine CLI:
  - `npx swallowkit machine inspect project`
  - `npx swallowkit machine validate project`
  - `npx swallowkit machine generate scaffold <name> --api-only`
- Do not hand-edit framework-owned artifacts when the MCP or machine interface can generate or validate them for you.
- The local MCP bootstrap expects project dependencies to already be installed.

<!--
- このリポジトリには、project-scoped な `.mcp.json` が含まれており、project MCP 設定を自動読込する runtime では同梱の SwallowKit MCP server を起動できます。
- framework 管理の inspect / validate / generate では、利用可能なら `swallowkit_*` MCP Tool を優先してください。
- runtime で MCP が使えない場合は、machine CLI にフォールバックしてください。
- MCP または machine interface で生成・検証できる framework 管理 artifact を手編集してはいけません。
-->

## Critical Design Principles

### 1. Next.js API Routes Are Strictly a BFF (Backend for Frontend)

- `app/api/` routes exist **only** to proxy requests to Azure Functions.
- **Never** place business logic, database access, or direct Cosmos DB calls in Next.js API routes.
- The BFF layer may validate input/output with Zod schemas before forwarding to Functions.
- Use the `callFunction` helper (`lib/api/call-function.ts`) or the `api` client (`lib/api/backend.ts`) to call Azure Functions.

Example BFF route pattern:

```typescript
// app/api/{model}/route.ts
import { callFunction } from '@/lib/api/call-function';
import { ModelSchema } from '@my-app/shared';
import { z } from 'zod/v4';

export async function GET() {
  return callFunction({
    method: 'GET',
    path: '/api/{model}',
    responseSchema: z.array(ModelSchema),
  });
}

export async function POST(request: NextRequest) {
  const body = await request.json();
  return callFunction({
    method: 'POST',
    path: '/api/{model}',
    body,
    inputSchema: ModelSchema.omit({ id: true, createdAt: true, updatedAt: true }),
    responseSchema: ModelSchema,
    successStatus: 201,
  });
}
```

### 2. Zod Schemas Are the Single Source of Truth

- All data models are defined **once** as Zod schemas in `shared/models/`.
- TypeScript types are derived with `z.infer<typeof Schema>` — never define types separately.
- The same schema is used in **all three layers**: frontend (validation), BFF (input/output validation), and Azure Functions (request/response validation + Cosmos DB documents).
- The shared package (`@my-app/shared`) is consumed by both Next.js and Azure Functions as a workspace dependency.

Model definition pattern:

```typescript
// shared/models/{model}.ts
import { z } from 'zod/v4';

export const Todo = z.object({
  id: z.string(),
  name: z.string().min(1),
  // ... your fields
  createdAt: z.string().optional(),
  updatedAt: z.string().optional(),
});

export type Todo = z.infer<typeof Todo>;
export const displayName = 'Todo';
```

Key rules:
- Use the **Zod official pattern**: the schema constant and the TypeScript type share the same name.
- `id`, `createdAt`, and `updatedAt` are auto-managed by the backend. Mark them as `optional()` in the schema.
- Always re-export models from `shared/index.ts`.

### 3. Azure Functions Own All Business Logic and Data Access

- All CRUD operations and business logic live in `functions/src/`.
- Use Azure Functions Cosmos DB **input/output bindings** (`extraInputs`/`extraOutputs`) for reads and writes.
- Use the Cosmos DB SDK client directly **only** for delete operations (bindings do not support delete).
- Validate all data against Zod schemas before writing to Cosmos DB.
- The backend auto-generates `id` (UUID), `createdAt`, and `updatedAt` — never trust client-sent values for these fields.

Azure Functions handler pattern:

```typescript
// functions/src/{model}.ts
import { app } from '@azure/functions';
import { ModelSchema } from '@my-app/shared';

const containerName = 'Models'; // PascalCase + 's'

app.http('{model}-get-all', {
  methods: ['GET'],
  route: '{model}',
  authLevel: 'anonymous',
  extraInputs: [{ type: 'cosmosDB', name: 'cosmosInput', containerName, ... }],
  handler: async (request, context) => {
    const documents = context.extraInputs.get('cosmosInput');
    const validated = z.array(ModelSchema).parse(documents);
    return { status: 200, jsonBody: validated };
  },
});
```

## Naming Conventions

| Item | Convention | Example |
|------|-----------|--------|
| Model schema file | `shared/models/{kebab-case}.ts` | `shared/models/todo.ts` |
| Schema/type name | PascalCase (same name for both) | `export const Todo = z.object({...}); export type Todo = z.infer<typeof Todo>;` |
| Functions handler file | `functions/src/{kebab-case}.ts` | `functions/src/todo.ts` |
| Functions handler name | `{camelCase}-{operation}` | `todo-get-all`, `todo-create` |
| API route path | `/api/{camelCase}` | `/api/todo`, `/api/todo/{id}` |
| BFF route file | `app/api/{kebab-case}/route.ts` | `app/api/todo/route.ts` |
| BFF detail route | `app/api/{kebab-case}/[id]/route.ts` | `app/api/todo/[id]/route.ts` |
| UI page directory | `app/{kebab-case}/` | `app/todo/page.tsx` |
| React component | PascalCase | `TodoForm.tsx` |
| Cosmos DB container | PascalCase + 's' | `Todos` |
| Cosmos DB partition key | `/id` (default) | Customizable via `export const partitionKey` in model file |
| Bicep container file | `infra/containers/{kebab-case}-container.bicep` | `infra/containers/todo-container.bicep` |

## Adding New Models (SwallowKit CLI Skills)

Use the SwallowKit CLI — do **not** manually create model files or CRUD boilerplate.

### Skill: Create a new data model

```bash
npx swallowkit create-model <name>
# Multiple models at once:
npx swallowkit create-model user post comment
```

Creates `shared/models/<name>.ts` with a Zod schema template including `id`, `createdAt`, `updatedAt`.
Edit the generated file to add your domain-specific fields, then run scaffold.

### Skill: Generate full CRUD from a model

```bash
npx swallowkit scaffold shared/models/<name>.ts
```

Generates:
- Azure Functions handlers (`functions/src/<name>.ts`)
- BFF API routes (`app/api/<name>/route.ts`, `app/api/<name>/[id]/route.ts`)
- UI pages (`app/<name>/page.tsx`, detail, create, edit pages)
- Cosmos DB Bicep container config (`infra/containers/<name>-container.bicep`)

### Skill: Start development servers

```bash
npx swallowkit dev
```

Runs Next.js (http://localhost:3000) and Azure Functions (http://localhost:7071) concurrently.
Checks for Cosmos DB Emulator availability.

### Skill: Provision Azure resources

```bash
npx swallowkit provision --resource-group <name>
```

Deploys Bicep infrastructure: Static Web Apps, Functions, Cosmos DB, Storage, Managed Identity.
Prompts for the primary region and the Static Web App region during execution.

### Typical workflow for "add a new feature/model"

1. `npx swallowkit create-model <name>`
2. Edit `shared/models/<name>.ts` — add fields
3. `npx swallowkit scaffold shared/models/<name>.ts`
4. `npx swallowkit dev` — verify at http://localhost:3000/<name>

## Do NOT

- **Do not** put business logic or database calls in `app/api/` routes. They are BFF only.
- **Do not** define TypeScript interfaces/types separately from Zod schemas. Always derive types with `z.infer<>`.
- **Do not** manually duplicate model definitions across layers. Use the shared package.
- **Do not** manually create CRUD boilerplate. Use `swallowkit scaffold`.
- **Do not** hardcode Cosmos DB connection strings. Use Managed Identity (`CosmosDBConnection__accountEndpoint`) in production and emulator settings locally.
- **Do not** change the partition key after a container is already created (it requires data migration). Configure it via `export const partitionKey` in model files before the first `swallowkit scaffold`.

## Technology Stack

- **Frontend**: Next.js (App Router), React, TypeScript, Tailwind CSS
- **BFF**: Next.js API Routes (proxy only)
- **Backend**: Azure Functions (TypeScript, Node.js)
- **Database**: Azure Cosmos DB (NoSQL)
- **Schema**: Zod (shared across all layers via workspace package)
- **Infrastructure**: Bicep (IaC)
- **Hosting**: Azure Static Web Apps (frontend) + Azure Functions Flex Consumption (backend)
- **Auth**: Azure Managed Identity (no connection strings in production)
- **Monitoring**: Application Insights

CLAUDE.md (Claude Code)

CLAUDE.md is a concise quick-reference file for Claude Code. It references AGENTS.md for the full specification and includes a CLI command table and workflow summary.

markdown

# CLAUDE.md

This file is for Claude Code. Read AGENTS.md in the project root for the full
architecture, conventions, and rules.

## Quick Reference

- **Architecture**: Next.js (frontend) → BFF (API routes, proxy only)
  → Azure Functions (backend) → Cosmos DB
- **Schema**: Zod schemas in `shared/models/` are the single source of truth.
  Never define types separately.
- **BFF rule**: `app/api/` routes must ONLY proxy to Azure Functions via
  `callFunction()`. No business logic.
- **Backend rule**: All business logic and Cosmos DB access lives in
  `functions/src/`.

## SwallowKit MCP

- This repository includes a project-scoped `.mcp.json` that registers the locally installed SwallowKit MCP server for runtimes that support project MCP files.
- When the `swallowkit_*` tools are available, prefer them for inspect / validate / generate tasks.
- If MCP is unavailable, use `npx swallowkit machine ...` instead.

## SwallowKit CLI Commands

| Task | Command |
|------|---------|
| Create model | `npx swallowkit create-model <name>` |
| Generate CRUD | `npx swallowkit scaffold shared/models/<name>.ts` |
| Dev servers | `npx swallowkit dev` |
| Provision Azure | `npx swallowkit provision -g <rg>` |

## Workflow: Add a new model

1. `npx swallowkit create-model <name>`
2. Edit `shared/models/<name>.ts` — add your fields
3. `npx swallowkit scaffold shared/models/<name>.ts`
4. `npx swallowkit dev` — verify at http://localhost:3000/<name>

.github/copilot-instructions.md (GitHub Copilot)

This file is automatically loaded by GitHub Copilot in VS Code. It contains a summary of the architecture, key rules, naming conventions, managed fields, and the MCP / machine-interface fallback path for framework-owned operations.

.github/instructions/*.instructions.md (GitHub Copilot — Layer-Specific)

These files provide context-specific rules that GitHub Copilot applies when editing files matching the applyTo glob pattern:

File	Applies To	Key Rules
`shared-models.instructions.md`	`shared/models/**`	Zod schema conventions, `id`/`createdAt`/`updatedAt` management, re-export from `shared/index.ts`
`bff-routes.instructions.md`	`app/api/**`	Proxy-only rule, `callFunction()` usage, no business logic
`azure-functions.instructions.md`	`functions/**`	Cosmos DB bindings, Zod validation, UUID auto-generation

Package Manager Detection

SwallowKit automatically selects the package manager:

If pnpm is installed on the system, pnpm is always preferred
Otherwise, npm is used

The generated project (lockfiles, workspace config, CI/CD scripts) matches the detected package manager.

Examples

bash

# Initialize in new directory (interactive)
npx swallowkit init my-awesome-app

# Initialize in new directory (non-interactive)
npx swallowkit init my-awesome-app --cicd github --cosmos-db-mode serverless --vnet outbound

# Using pnpm
pnpm dlx swallowkit init my-awesome-app

# After initialization
cd my-awesome-app

swallowkit create-model

Create one or more Zod model template files under shared/models/.

Usage

bash

npx swallowkit create-model <names...> [options]
# or
pnpm dlx swallowkit create-model <names...> [options]

Arguments

names...: One or more model names

Options

Option	Description	Default
`--models-dir <dir>`	Output directory for generated model files	`shared/models`
`--connector <name>`	Create a connector-aware model linked to the named connector	(none)

What it does

For each model name, the command:

creates shared/models/<name>.ts
normalizes the file name to kebab-case and the schema/type name to PascalCase
adds a re-export to shared/index.ts when that file exists
includes id, name, createdAt, and updatedAt in the starter schema

Example:

bash

npx swallowkit create-model todo category

Generated template:

typescript

import { z } from 'zod/v4';

export const Todo = z.object({
  id: z.string(),
  name: z.string().min(1),
  createdAt: z.string().optional(),
  updatedAt: z.string().optional(),
});

export type Todo = z.infer<typeof Todo>;
export const displayName = 'Todo';

Connector model

When --connector is specified, the generated template includes a connectorConfig export with connector-specific metadata:

RDB connectors: includes table and idColumn fields
API connectors: includes endpoints mapping
Both include an operations array (defaults to all operations for API, read-only for RDB)
The Zod schema template is adapted (no createdAt/updatedAt auto-management by backend)

Example:

bash

npx swallowkit create-model user --connector mysql
npx swallowkit create-model backlog-issue --connector backlog

Existing file behavior

If the target file already exists, the command asks whether it should overwrite that file. If you answer no, that model is skipped and the remaining models continue.

Typical workflow

bash

npx swallowkit create-model todo
# edit shared/models/todo.ts
npx swallowkit scaffold shared/models/todo.ts

Use create-model to create the initial schema stub, then customize the generated Zod model before running scaffold.

swallowkit add-connector

Usage

bash

npx swallowkit add-connector <name> --type=<type> [options]
# or
pnpm dlx swallowkit add-connector <name> --type=<type> [options]

Arguments

name (required): Connector name (used as key in config)

Options

Option	Description	Required
`--type <type>`	Connector type: `rdb` or `api`	Yes
`--provider <provider>`	RDB provider: `mysql`, `postgres`, `sqlserver`	Only for `--type rdb`
`--connection-env <var>`	Environment variable for connection string	Only for `--type rdb`
`--base-url-env <var>`	Environment variable for API base URL	Only for `--type api`
`--auth-type <type>`	Auth type: `apiKey`, `bearer`, `oauth2`	Only for `--type api`
`--auth-env <var>`	Environment variable for auth credential	Only for `--type api`
`--auth-placement <placement>`	Where to place auth: `query` or `header`	Only for `--type api` with `apiKey`
`--auth-param <name>`	Parameter name for API key	Only for `--type api` with `apiKey`

What it does

Reads existing swallowkit.config.js
Adds the connector definition to the connectors section
Creates the connectors section if it doesn't exist

Examples

bash

# Add MySQL RDB connector
npx swallowkit add-connector mysql --type rdb --provider mysql --connection-env MYSQL_CONNECTION_STRING

# Add REST API connector with API key auth
npx swallowkit add-connector backlog --type api --base-url-env BACKLOG_API_BASE_URL --auth-type apiKey --auth-env BACKLOG_API_KEY --auth-placement query --auth-param apiKey

# Add REST API connector with bearer token
npx swallowkit add-connector github --type api --base-url-env GITHUB_API_BASE_URL --auth-type bearer --auth-env GITHUB_TOKEN

swallowkit add-auth

Set up authentication and authorization infrastructure for a SwallowKit project.

Usage

bash

npx swallowkit add-auth [options]
# or
pnpm dlx swallowkit add-auth [options]

Options

Option	Description	Values	Default
`--provider <provider>`	Authentication provider	`custom-jwt`	`custom-jwt`

Note: swa and swa-custom are reserved for future releases, but are not implemented by the current generated auth flow.

What it does

Generates shared auth models (shared/models/auth.ts — LoginRequest, AuthUser, LoginResponse)
Generates auth Functions (login, me, logout) for the configured backend language (TS/C#/Python)
Generates JWT helper utilities for token verification and role checking
Generates BFF routes (app/api/auth/login|logout|me/route.ts) with httpOnly cookie management
Generates Next.js middleware (middleware.ts) for cookie-based auth checks and redirects
Generates a login page (app/login/page.tsx)
Generates an auth React context (lib/auth/auth-context.tsx) with useAuth hook
Updates lib/api/call-function.ts to forward the Authorization header
Adds auth section to swallowkit.config.js if not present
Installs backend dependencies (JWT library + RDB driver matching your connector provider)

Prerequisites

A connector must be registered in swallowkit.config.js for the user database (e.g., an RDB connector pointing to PostgreSQL, MySQL, or SQL Server)
The auth.customJwt.userConnector config must reference that connector name

Examples

bash

# Set up custom JWT authentication (default)
npx swallowkit add-auth

# Explicitly specify provider
npx swallowkit add-auth --provider custom-jwt

Typical workflow

bash

# 1. Add RDB connector for user database
npx swallowkit add-connector userdb --type rdb --provider postgres --connection-env USERDB_CONNECTION_STRING

# 2. Configure auth in swallowkit.config.js (add auth section)

# 3. Run add-auth to generate all auth infrastructure
npx swallowkit add-auth

# 4. Set JWT_SECRET in functions/local.settings.json

# 5. Add authPolicy to models for role-based access
# 6. Re-scaffold to inject auth guards into functions
npx swallowkit scaffold shared/models/estimate.ts

# 7. Start development with mock connectors (user data is also mocked)
npx swallowkit dev --mock-connectors

💡 See the Authentication Guide for full configuration details and architecture overview.

swallowkit dev

Start development servers (Next.js + Azure Functions).

Usage

bash

npx swallowkit dev [options]
# or
pnpm dlx swallowkit dev [options]

Options

Option	Short	Description	Default
`--port <port>`	`-p`	Next.js port	`3000`
`--functions-port <port>`		Azure Functions port	`7071`
`--host <host>`		Host name	`localhost`
`--open`	`-o`	Auto-open browser	`false`
`--no-functions`		Skip Functions	`false`
`--seed-env <environment>`		Replace matching Cosmos Emulator containers from `dev-seeds/<environment>` before startup	(disabled)
`--mock-connectors`		Start a mock proxy server for connector models	`false`
`--verbose`	`-v`	Show detailed logs	`false`

Behavior

Cosmos DB Emulator Check: Verify local emulator is running
Cosmos DB Initialization:
- Create database if needed
- Create model containers if needed
- If --seed-env <environment> is provided and dev-seeds/<environment>/ exists, replace each matching container with the JSON documents from that environment
Connector Mock Server (when --mock-connectors is enabled):
- Starts a proxy server on Functions port + 1 (e.g., 7072)
- Routes matching connector models → in-memory CRUD with Zod-generated mock data
- All other routes → proxied to real Azure Functions
- Loads dev-seeds JSON as initial data if available
- BFF automatically routes through the mock proxy (no config change needed)
Azure Functions Start:
- Check Azure Functions Core Tools
- Auto-install dependencies
- Start Functions in functions/ directory
- Python backend: use uv for local runtime management, keeping project-local state under .uv/, creating functions/.venv for the app, and functions/.codegen-venv for Python schema generation
- C# backend: allow extra cold-start time for the isolated worker build, and only report the Functions URL as ready after the host answers HTTP requests
Next.js Start: Launch development server

Dev Seed Workflow

Use environment-specific seed data when you want reproducible emulator state for debugging:

bash

npx swallowkit create-dev-seeds local
# edit dev-seeds/local/*.json
npx swallowkit dev --seed-env local

Rules:

File naming follows your schema files, for example shared/models/todo.ts -> dev-seeds/local/todo.json
Each matching seed file replaces the entire contents of the corresponding Cosmos container
Containers without a matching seed file are not modified
If --seed-env is omitted, or the environment directory does not exist, existing emulator data is preserved
Each document must have a non-empty string id

Example:

json

[
  {
    "id": "seed-todo-001",
    "name": "Seed todo one",
    "createdAt": "2026-03-21T00:00:00.000Z",
    "updatedAt": "2026-03-21T00:00:00.000Z"
  }
]

Examples

bash

# Start with default settings
npx swallowkit dev

# Start with custom ports
npx swallowkit dev --port 3001 --functions-port 7072

# Auto-open browser
npx swallowkit dev --open

# Next.js only (no Functions)
npx swallowkit dev --no-functions

# Start with a seed environment
npx swallowkit dev --seed-env local

# Verbose logging
npx swallowkit dev --verbose

# Start with connector mock server
npx swallowkit dev --mock-connectors

# Combine mock connectors with seed data
npx swallowkit dev --mock-connectors --seed-env local

Troubleshooting

Cosmos DB Emulator not found:

Error: Cosmos DB Emulator is not running

Solution:

Windows: Install from official site
Docker: docker run -p 8081:8081 mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator

Azure Functions Core Tools missing:

Error: Azure Functions Core Tools not found

Solution:

bash

npm install -g azure-functions-core-tools@4
# or
pnpm add -g azure-functions-core-tools@4

Port in use:

Error: Port 3000 is already in use

Solution:

bash

npx swallowkit dev --port 3001

swallowkit scaffold

Auto-generate CRUD operations from Zod schemas.

Usage

bash

npx swallowkit scaffold <model-file> [options]
# or
pnpm dlx swallowkit scaffold <model-file> [options]

Arguments

model-file (required): Path to model file containing Zod schema

Options

Currently no options.

Connector model behavior

When a model file contains a connectorConfig export, scaffold detects it as a connector model:

RDB connector models: generates SQL-based CRUD handlers in functions/Connectors/ (C#) or equivalent
API connector models: generates HTTP client handlers
BFF routes and React UI are generated identically to standard models
Cosmos DB Bicep generation is skipped for connector models
Read-only models (operations limited to getAll/getById) only get GET endpoints

Generated Code

1. Azure Functions (CRUD endpoints)

typescript

// functions/src/functions/{resource}.ts
- GET    /api/{resource}       - Get all
- GET    /api/{resource}/{id}  - Get by ID
- POST   /api/{resource}       - Create
- PUT    /api/{resource}/{id}  - Update
- DELETE /api/{resource}/{id}  - Delete

Each endpoint includes:

✅ Cosmos DB input/output bindings
✅ Automatic Zod schema validation
✅ Error handling
✅ TypeScript type safety
✅ Factory pattern support (shared crud-factory.ts)

2. Next.js BFF API Routes

typescript

// app/api/{resource}/route.ts
// app/api/{resource}/[id]/route.ts

Each route:

✅ Calls Azure Functions backend
✅ Automatic schema validation
✅ Error handling

3. React Components (optional)

typescript

// components/{Resource}List.tsx
// components/{Resource}Form.tsx

Prerequisites

Model file requirements:

typescript

// lib/models/todo.ts
import { z } from 'zod';

// 1. Define Zod schema
export const todoSchema = z.object({
  id: z.string(),
  text: z.string().min(1),
  completed: z.boolean().default(false),
  createdAt: z.string().default(() => new Date().toISOString()),
});

// 2. Infer type from schema
export type TodoType = z.infer<typeof todoSchema>;

Examples

bash

# Generate CRUD from Todo model
npx swallowkit scaffold lib/models/todo.ts

# Generate CRUD from Product model
npx swallowkit scaffold lib/models/product.ts

Usage After Generation

From frontend:

typescript

import { api } from '@/lib/api/backend';
import type { TodoType } from '@/lib/models/todo';

// Get all
const todos = await api.get<TodoType[]>('/api/todos');

// Create (validated by backend)
const created = await api.post<TodoType>('/api/todos', {
  text: 'Buy milk',
  completed: false
});

// Update (validated by backend)
const updated = await api.put<TodoType>('/api/todos/123', {
  completed: true
});

// Delete
await api.delete('/api/todos/123');

Details

See Scaffold Guide for more information.

swallowkit create-dev-seeds

Generate JSON seed templates for a named local environment from the current schemas in shared/models/.

Usage

bash

npx swallowkit create-dev-seeds <environment> [options]
# or
pnpm dlx swallowkit create-dev-seeds <environment> [options]

Arguments

environment (required): Name of the seed environment directory under dev-seeds/

Options

Option	Description	Default
`--models-dir <dir>`	Models directory to read schemas from	`shared/models`
`--seeds-dir <dir>`	Base directory for generated seed environments	`dev-seeds`
`--force`	Overwrite existing JSON seed files	`false`

What It Generates

For every schema under shared/models/, SwallowKit generates a JSON file under dev-seeds/<environment>/:

text

dev-seeds/
  local/
    todo.json
    category.json

Template values are inferred from schema field types:

strings -> sample strings
numbers -> 0
booleans -> false
enums -> first enum value
...At/date fields -> ISO timestamp sample
nested schemas -> nested JSON objects

Typical Workflow

bash

npx swallowkit create-model todo
npx swallowkit scaffold shared/models/todo.ts
npx swallowkit create-dev-seeds local
# edit dev-seeds/local/todo.json
npx swallowkit dev --seed-env local

swallowkit provision

Provision Azure resources using Bicep.

Usage

bash

npx swallowkit provision [options]
# or
pnpm dlx swallowkit provision [options]

Options

Option	Short	Description	Required
`--resource-group <name>`	`-g`	Resource group name	✅
`--subscription <id>`		Subscription ID

Region Selection

The command prompts for these regions interactively:

Primary location for Functions and Cosmos DB
Static Web App location

Recommended region combinations:

japaneast + eastasia
japanwest + eastasia
eastus2 + eastus2
westeurope + westeurope

Primary location choices:

japaneast - Japan East
japanwest - Japan West
eastasia - East Asia
southeastasia - Southeast Asia
eastus - East US
eastus2 - East US 2
westus2 - West US 2
centralus - Central US
westeurope - West Europe

Static Web App location choices:

eastasia - Recommended for Japan
westus2 - West US 2
centralus - Central US
eastus2 - East US 2
westeurope - West Europe

List all regions:

bash

az account list-locations --output table

Generated Resources

Azure Static Web Apps
- SKU: Free
- Build config: standalone Next.js
Azure Functions
- Plan: Flex Consumption
- Runtime: Node.js 22
- OS: Linux
Azure Cosmos DB
- Mode: Free Tier or Serverless (selected during initialization)
- API: NoSQL
- Consistency: Session
Azure Storage Account
- For Functions storage
- SKU: Standard_LRS
Managed Identity
- Type: System-assigned
- Role: Cosmos DB Data Contributor

Examples

bash

# Basic usage
npx swallowkit provision --resource-group my-app-rg

# With subscription
npx swallowkit provision \
  --resource-group my-app-rg \
  --subscription "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

After Provisioning

bash

# List resources
az resource list --resource-group my-app-rg --output table

# Get Static Web Apps URL
az staticwebapp show \
  --name <swa-name> \
  --resource-group my-app-rg \
  --query "defaultHostname" -o tsv

# Get Functions URL
az functionapp show \
  --name <function-name> \
  --resource-group my-app-rg \
  --query "defaultHostName" -o tsv

Customizing Bicep Files

Edit Bicep files in infra/ before provisioning:

bicep

// infra/modules/functions-flex.bicep

// Customize instance memory size
resource flexFunctionsServer 'Microsoft.Web/sites@2023-12-01' = {
  // Flex Consumption properties
}

After editing, run swallowkit provision again to apply changes.

Troubleshooting

Resource group doesn't exist:

bash

# Create it
az group create --name my-app-rg --location japaneast

Resources unavailable in region:

bash

# Check available regions
az provider show --namespace Microsoft.Web \
  --query "resourceTypes[?resourceType=='staticSites'].locations" -o table

Quota exceeded:

bash

# Check quota
az vm list-usage --location japaneast --output table

Global Options

Available for all commands:

Option	Description
`--help`	Show help
`--version`	Show version

Environment Variables

Control CLI behavior with environment variables:

Variable	Description	Default
`SWALLOWKIT_LOG_LEVEL`	Log level (debug/info/warn/error)	`info`
`COSMOS_DB_ENDPOINT`	Cosmos DB endpoint	`https://localhost:8081/`
`BACKEND_API_URL`	Functions URL	`http://localhost:7071`

Next Steps

Deployment Guide - Deploy to Azure
Scaffold Guide - CRUD code generation details

CLI Reference ​

Table of Contents ​

swallowkit machine ​

Usage ​

Available commands ​

Examples ​

Output contract ​

swallowkit-mcp ​

Usage ​

Exposed MCP tools ​

swallowkit init ​

Usage ​

Arguments ​

Options ​

Interactive vs Non-Interactive Mode ​

Interactive Prompts ​

Backend Language Notes ​

Generated Files ​

AI Agent Bootstrap Files ​

Generated Files ​

CLAUDE.md (Claude Code) ​

.github/copilot-instructions.md (GitHub Copilot) ​

.github/instructions/*.instructions.md (GitHub Copilot — Layer-Specific) ​

Package Manager Detection ​

Examples ​

swallowkit create-model ​

Usage ​

Arguments ​

Options ​

What it does ​

Connector model ​

Existing file behavior ​

Typical workflow ​

swallowkit add-connector ​

Usage ​

Arguments ​

Options ​

What it does ​

Examples ​

swallowkit add-auth ​

Usage ​

Options ​

What it does ​

Prerequisites ​

Examples ​

Typical workflow ​

swallowkit dev ​

Usage ​

Options ​

Behavior ​

Dev Seed Workflow ​

Examples ​

Troubleshooting ​

swallowkit scaffold ​

Usage ​

Arguments ​

Options ​

Connector model behavior ​

Generated Code ​

Prerequisites ​

Examples ​

Usage After Generation ​

Details ​

swallowkit create-dev-seeds ​

Usage ​

Arguments ​

Options ​

What It Generates ​

Typical Workflow ​

swallowkit provision ​

Usage ​

Options ​

Region Selection ​

Generated Resources ​

Examples ​

After Provisioning ​

Customizing Bicep Files ​

Troubleshooting ​

Global Options ​

Environment Variables ​

CLI Reference

Table of Contents

swallowkit machine

Usage

Available commands

Examples

Output contract

swallowkit-mcp

Usage

Exposed MCP tools

swallowkit init

Usage

Arguments

Options

Interactive vs Non-Interactive Mode

Interactive Prompts

Backend Language Notes

Generated Files

AI Agent Bootstrap Files

Generated Files

CLAUDE.md (Claude Code)

.github/copilot-instructions.md (GitHub Copilot)

.github/instructions/*.instructions.md (GitHub Copilot — Layer-Specific)

Package Manager Detection

Examples

swallowkit create-model

Usage

Arguments

Options

What it does

Connector model

Existing file behavior

Typical workflow

swallowkit add-connector

Usage

Arguments

Options

What it does

Examples

swallowkit add-auth

Usage

Options

What it does

Prerequisites

Examples

Typical workflow

swallowkit dev

Usage

Options

Behavior

Dev Seed Workflow

Examples

Troubleshooting

swallowkit scaffold

Usage

Arguments

Options

Connector model behavior

Generated Code

Prerequisites

Examples

Usage After Generation

Details

swallowkit create-dev-seeds

Usage

Arguments

Options

What It Generates

Typical Workflow

swallowkit provision

Usage

Options

Region Selection

Generated Resources

Examples

After Provisioning

Customizing Bicep Files

Troubleshooting

Global Options

Environment Variables