@swizzyweb/swizzy-web-service-cli

CLI and TUI for scaffolding and managing @swizzyweb/swizzy-web-service projects.

Installation

npm install -g @swizzyweb/swizzy-web-service-cli

Usage

Run without arguments to launch the interactive TUI:

swizzy

Or pass a command directly for non-interactive use:

swizzy <command> [options]

Commands

create-web-service

Scaffold a new swizzy-web-service project.

swizzy create-web-service --name <name> [--type <type>] [--scope <scope>] [--install]

| Option | Required | Default | Description | |---|---|---|---| | --name <name> | Yes | — | Service name in PascalCase — do not include "Service" (e.g. MyApi, not MyApiService) | | --type <type> | No | backend | backend (API only) or frontend (React + API) | | --scope <scope> | No | — | npm scope without @ (e.g. myorg → @myorg/my-api-web-service) | | --install | No | false | Run npm install after scaffolding |

Examples:

# Backend service
swizzy create-web-service --name MyApi --type backend

# Frontend service with npm scope
swizzy create-web-service --name MyApp --type frontend --scope myorg --install

The project is created in ./<kebab-name>-web-service/ relative to the current directory. It is pre-wired with a Hello router and a World GET controller (query param: name: string) so the project compiles and runs immediately. If --install is not passed, the CLI prints the next steps.

create-router

Add a new WebRouter to the project in the current directory. Creates the router file and automatically patches src/web-service.ts to import and register it.

swizzy create-router --name <name> --path <path> [--no-standard-middleware]

| Option | Required | Default | Description | |---|---|---|---| | --name <name> | Yes | — | Router name in PascalCase (e.g. Message) | | --path <path> | Yes | — | URL path segment (e.g. message) | | --no-standard-middleware | No | off | Omit SwizzyRequestMiddleware, RequestIdMiddleware, and RequestLoggerMiddleware |

Examples:

# Router at /api/message with standard middleware
swizzy create-router --name Message --path message

# Router without standard middleware
swizzy create-router --name Health --path health --no-standard-middleware

Output: Creates src/routers/MessageRouter/message-router.ts and patches src/web-service.ts.

Must be run from the root of a swizzy-web-service project.

create-controller

Add a new WebController to an existing router. Creates the controller file, a test skeleton, and automatically patches the parent router file to import and register it.

swizzy create-controller --name <name> --action <action> --router <router> [--method <method>] [--body] [--query]

| Option | Required | Default | Description | |---|---|---|---| | --name <name> | Yes | — | Controller name in PascalCase (e.g. SendMessage) | | --action <action> | Yes | — | Action name / URL segment (e.g. send) | | --router <router> | Yes | — | Parent router name in PascalCase (e.g. Message) | | --method <method> | No | get | HTTP method: get post put delete patch | | --body | No | off | Generate typed request body + JSON validation middleware | | --query | No | off | Generate typed query params + validation middleware |

Examples:

# Plain GET controller
swizzy create-controller --name GetUptime --action uptime --router Statistics

# POST controller with a request body
swizzy create-controller --name SendMessage --action send --router Message --method post --body

# GET controller with query parameters
swizzy create-controller --name GetMessage --action get --router Message --query

# DELETE controller
swizzy create-controller --name DeleteMessage --action delete --router Message --method delete

Output: Creates:

• src/routers/MessageRouter/controllers/send-controller.ts
• test/routers/MessageRouter/controllers/send-controller.spec.ts

And patches src/routers/MessageRouter/message-router.ts.

Must be run from the root of a swizzy-web-service project.

build

Build the project.

swizzy build

Runs npm install first if node_modules is missing, then runs npm run build in the current directory.

run

Run the web service using swerve.

swizzy run [--port <port>]

| Option | Required | Default | Description | |---|---|---|---| | --port <port> | No | swerve default | Port to bind the service to |

swizzy run --port 3005

Runs npm install first if node_modules is missing. Press Ctrl+C to stop.

dev

Start a development server that watches for TypeScript changes and auto-restarts the service.

swizzy dev [--port <port>]

| Option | Required | Default | Description | |---|---|---|---| | --port <port> | No | swerve default | Port to bind the service to |

swizzy dev --port 3005

Runs npm install first if node_modules is missing. Then runs tsc --watch in the background — when compiled output changes in dist/, swerve is restarted automatically. Press Ctrl+C to stop everything.

generate-tests

Generate multi-case test stubs for all routers and controllers in the current project. Produces a shared test helper and individual test files with happy-path (200), per-missing-field (400), and error (500) cases.

swizzy generate-tests

Uses @swizzyweb/swizzy-web-service-test-framework for the generated helper and test setup. Existing test files are skipped. Must be run from the root of a swizzy-web-service project.

Output:

• test/helpers/test-helper.ts — shared setup function (created once, skipped if present)
• test/routers/<Router>/controllers/<action>-controller.spec.ts — one file per controller

generate-spec

Generate an OpenAPI 3.0 spec from the current swizzy-web-service project by introspecting routers and controllers.

swizzy generate-spec [--output <file>] [--base-path <path>] [--server-url <url>] [--version <version>] [--json]

| Option | Required | Default | Description | |---|---|---|---| | --project-dir <dir> | No | cwd | Path to the swizzy project | | --output <file> | No | openapi.yaml | Output file path | | --base-path <path> | No | auto-detected | API base path (e.g. api) | | --server-url <url> | No | — | Server URL to embed (e.g. http://localhost:3000) | | --version <version> | No | 1.0.0 | API version string | | --json | No | off | Write JSON instead of YAML |

Examples:

# Generate openapi.yaml in the project root
swizzy generate-spec

# Generate with a server URL and JSON output
swizzy generate-spec --server-url http://localhost:3000 --json --output openapi.json

Must be run from (or pointed at) the root of a swizzy-web-service project.

generate-skeleton

Generate a swizzy-web-service project skeleton from an OpenAPI 3.0 spec. Creates routers, controllers, models, and services wired together based on the paths defined in the spec.

swizzy generate-skeleton --spec <file> [--output <dir>] [--name <name>] [--scope <scope>] [--base-path <path>]

| Option | Required | Default | Description | |---|---|---|---| | --spec <file> | Yes | — | Path to the OpenAPI 3.0 spec (JSON or YAML) | | --output <dir> | No | ./generated | Output directory | | --name <name> | No | derived from spec | Service name override in PascalCase | | --scope <scope> | No | — | npm scope for the generated package (e.g. myorg) | | --base-path <path> | No | api | API base path for the generated service |

Examples:

# Generate from a local spec into ./generated
swizzy generate-skeleton --spec openapi.yaml

# Generate with a custom output directory and package scope
swizzy generate-skeleton --spec openapi.json --output ./my-service --scope myorg --name MyApi

Only OpenAPI 3.0.0 specs are supported. The generated project uses the same structure as create-web-service.

request

Send an HTTP request to a running swizzy-web-service. Introspects the current project to discover available endpoints.

swizzy request [--base-url <url>] [--endpoint <endpoint>] [--body <json>] [--query <json>] [--project-dir <dir>]

| Option | Required | Default | Description | |---|---|---|---| | --base-url <url> | No | http://localhost:3000 | Base URL of the running service | | --endpoint <endpoint> | No | — | Endpoint label to call (e.g. "POST /api/message/send") | | --body <json> | No | — | JSON request body (e.g. '{"text":"hello"}') | | --query <json> | No | — | JSON query params (e.g. '{"limit":"10"}') | | --project-dir <dir> | No | cwd | Path to the swizzy project |

Run without --endpoint to list all available endpoints and their field signatures:

swizzy request
# Available endpoints:
#   [1] POST /api/message/send
#         body.text: string
#   [2] GET /api/message/get
#         query.id: string

Examples:

# List endpoints
swizzy request

# Send a POST request with a JSON body
swizzy request --endpoint "POST /api/message/send" --body '{"text":"hello"}'

# Send a GET request with query params against a custom base URL
swizzy request --base-url http://localhost:3005 --endpoint "GET /api/message/get" --query '{"id":"123"}'

Must be run from (or pointed at) the root of a swizzy-web-service project.

Naming Conventions

The CLI derives file names, class names, and directory names from the input you provide. Service names should not include "Service" — the CLI appends it automatically. Given a service name of MyApi:

| Derived | Value | |---|---| | Project directory | my-api-web-service/ | | Package name | @scope/my-api-web-service | | Service class | MyApiWebService |

Given a router name of Message:

| Derived | Value | |---|---| | Class name | MessageWebRouter | | File name | message-router.ts | | Directory | src/routers/MessageRouter/ | | State type | MessageRouterState |

Given a controller name of SendMessage with action send:

| Derived | Value | |---|---| | Class name | SendMessageController | | File name | send-controller.ts | | Directory | src/routers/MessageRouter/controllers/ | | State type | SendMessageControllerState |

Project Structure

A project created with create-web-service --name MyApi looks like this:

my-api-web-service/
├── package.json
├── tsconfig.json
└── src/
    ├── app.ts              # getWebservice() entry point
    ├── web-service.ts      # MyApiWebService class
    └── routers/
        └── HelloRouter/
            ├── hello-router.ts
            └── controllers/
                └── world-controller.ts

After adding routers and controllers:

my-api-web-service/
└── src/
    ├── app.ts
    ├── web-service.ts
    └── routers/
        ├── HelloRouter/
        │   ├── hello-router.ts
        │   └── controllers/
        │       └── world-controller.ts
        └── MessageRouter/
            ├── message-router.ts
            └── controllers/
                └── send-controller.ts

TUI

Running swizzy with no arguments opens the interactive TUI. If run from a directory containing multiple swizzy projects, a project picker is shown first.

swizzy — @swizzyweb/swizzy-web-service-cli

Select an action:
❯ Manage project (tree view)
  Create new web service
  Add router to current project
  Add controller to current project
  Build project (npm run build)
  Run service (swerve)
  Dev server (watch + auto-restart)
  Generate OpenAPI spec from project
  Generate skeleton from OpenAPI spec
  Generate tests for current project
  Send request to running service

Navigate with arrow keys, confirm with Enter. Pressing i or Enter on a router/controller node in the Manage screen opens a detail panel showing its path, HTTP method, middleware, request body/query fields, and service args.

The Send request to running service screen walks you through the request interactively: enter a base URL, pick an endpoint from the detected project, fill in any body or query fields one at a time, then see the status code, response time, and body.