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

create-router

Add a new WebRouter to the project.

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

create-controller

Add a new WebController to an existing router.

swizzy create-controller --name <name> --action <action> --router <router> [--method <method>] [--body] [--query] [--implementation-file <path>] [--import <statement>]

--implementation-file reads a file and uses its contents as the getInitializedController body, set at creation time. --import (repeatable) adds any extra import statements the implementation needs.

Controllers generated with --body or --query use SwizzyJsonMiddleware from @swizzyweb/swizzy-web-service for JSON body parsing instead of Express's raw json() middleware.

update-controller-implementation

Replace the getInitializedController body of an existing controller. Prefer this over hand-editing the controller file — it patches only the method body and validates the result is syntactically valid TypeScript before writing, so the surrounding state/request interfaces are never disturbed.

swizzy update-controller-implementation --router <router> --controller <ctrl> --implementation-file <path> [--import <statement>]

update-middleware-implementation

Replace a middleware's handler body, the same way as above.

swizzy update-middleware-implementation --router <router> --middleware <name> --implementation-file <path> [--import <statement>]

add-jsdoc

Add JSDoc comments to routers and controllers in the current project. Targets the whole project by default, or a specific router/controller with --router / --controller.

swizzy add-jsdoc [--router <name>] [--controller <name>]

manage-state

Manage state properties with automatic upward propagation (Controller → Router → WebService → app.ts).

swizzy manage-state --action <add|update|delete> --level <controller|router|service> --name <propName> [--router <router>] [--controller <ctrl>] [--type <type>] [--default <val>]

update-controller-params

Update or delete request body/query parameters for an existing controller.

swizzy update-controller-params --router <router> --controller <ctrl> [--action <upsert|delete>] [--body <fields>] [--query <params>]

add-service-arg / update-service-arg / delete-service-arg

Manage typed service arguments in app.ts and all web-service-config*.json files.

swizzy add-service-arg --name <name> --type <type> [--default <val>]
swizzy update-service-arg --name <name> [--type <newType>] [--default <newVal>]
swizzy delete-service-arg --name <name>

generate-config

Generate a baseline web-service-config.json for a project using its packageName.

swizzy generate-config [--force]

upsert-stack

Create or update a multi-service stack configuration. Handles local paths (auto-detects class names) and NPM packages.

swizzy upsert-stack --service <[ClassName:]location> [--service ...]

Example: swizzy upsert-stack --service MyBackend:./backend --service MyProxy:@swizzyweb/proxy-web-service

list-configs / read-config

Discover and inspect configuration files in the workspace.

swizzy list-configs
swizzy read-config --path <path>

remove-from-stack

Delete a service definition from a stack configuration.

swizzy remove-from-stack --name <ClassName>

build

Build the project (runs npm run build).

run / dev

Run the service or start a dev server with watch mode and auto-restart.

logs

View the most recent logs for a running Swizzy web service or stack.

swizzy logs [dir] [-n, --lines <number>] [-f, --follow]

generate-tests

Generate test stubs for controllers that don't have one yet. Automatically adds @swizzyai/swizzy-web-service-test-framework as a devDependency if it is not already present.

swizzy generate-tests

generate-spec

Generate an OpenAPI 3.0 spec from the current project. Can also scaffold a Node.js client package using @hey-api/openapi-ts.

swizzy generate-spec [--json] [--output <path>] [--client-package] [--client-package-name <name>] [--client-output <dir>]

generate-skeleton

Scaffold a new project from an OpenAPI 3.0 spec file.

swizzy generate-skeleton --spec <path> [--output <dir>]

request

Interactively send HTTP requests to discovered endpoints.

---

TUI

The interactive TUI has been enhanced with a new Action Menu. Press Enter on any component in the project tree to access all management tasks:

• Manage State: Interactively add/update/delete state properties with propagation.
• Manage Parameters: Add/modify/delete request body and query fields.
• Compose Stack: Build multi-service configurations.
• Config Discovery: Scan the workspace for configuration files.

---

Technical Features

• Robust Patching: AST patchers automatically repair missing commas/semicolons and handle complex nested structures via brace-counting.
• Syntax Validation: Implementation commands run the TypeScript compiler API over the patched source before writing to disk — invalid patches are rejected without touching the file.
• Safe Implementation Editing: update-controller-implementation and update-middleware-implementation surgically replace only the method body, leaving all surrounding interfaces and imports intact.
• Navigation: Full Escape key support and consistent "Back" options throughout.