@sculptor/cli

The SculptorTS CLI is the user-facing command line for the framework.

It handles:

• New app scaffolding
• Resource generation
• Test generation and registry syncing
• Dev and production startup paths
• Help and version output
• App dependency recovery with sc install deps
• Global package refresh with sc update
• Scaffolded .gitignore generation

Version Policy

• Deprecated range: 0.2.0 through 0.2.3
• Current stable: 0.2.4
• Reason: the earlier release predates the current template-registry layout, the sc config command set, the sc install deps and sc update commands, and the route/handler generation contract used by the current CLI.

Quick Command Sheet

| Command | What it does | | --- | --- | | sc new <app> | Creates a new app | | sc dev | Starts the app from source | | sc start | Starts the app in production-style mode | | sc build | Builds the app | | sc lint | Lints the app | | sc test | Runs the test suite | | sc config get <path> | Reads a config value | | sc config set <path=value> | Writes a config value | | sc config list | Lists the merged config | | sc install deps | Replays app dependency installs inside a Sculptor app | | sc i deps | Alias for sc install deps | | sc update | Updates globally installed Sculptor packages outside an app | | sc generate / sc g | Generates framework resources | | sc g c user | Generates a controller resource | | sc g r user | Generates a functional route and handler pair | | sc g c user in src/app/users | Generates into a custom path | | sc g c in src/app/users | Infers the name from the path and generates there | | sc g t user -e | Generates an enum type file | | sc g t user -i | Generates an interface type file | | sc g t user -c | Generates a class type file | | sc v / sc --v / sc -v | Prints version | | sc help | Prints help |

Entry Points

• Primary Binary: sc
• Fallback Binary: sculptor
• Temporary Execution (via Package Runner): npx sc or npx sculptor
• Programmatic API: runCli()

Note: If the Binary: sc resolves to Windows Service Control or conflicts with any other Binary, use sculptor instead. Otherwise use npx as prefix to invoke the CLI via Package Runner.

Command Reference

sc new <app>

What it does:

• Creates a new Sculptor app in a sibling folder
• Writes the initial framework files
• Installs the package dependencies

How it is used:

sc new my-app

Flags:

| Flag | Meaning | | --- | --- | | --name <value> | Sets the app name | | --version <value> | Sets the scaffolded app version | | --style <decorator/functional/hybrid> | Sets the routing mode | | --decorator | Shortcut for decorator mode | | --functional | Shortcut for functional mode | | --hybrid | Shortcut for hybrid mode | | --frameworkLock <true/false> | Sets framework lock | | --frameworklock <true/false> | Alias for framework lock | | --framework-lock <true/false> | Alias for framework lock | | --dev-server <tsx/nodemon> | Selects the dev server | | --devserver <tsx/nodemon> | Alias for dev server | | --tsx | Shortcut for tsx dev server | | --nodemon | Shortcut for nodemon dev server |

Examples:

sc new api
sc new api --style=hybrid
sc new api --dev-server=nodemon
sc new api --framework-lock=false

What it solves:

• You get a ready-to-run app with the framework defaults already wired

You will find it here:

• packages/cli/src/cli.ts
• packages/cli/src/scaffold.ts
• packages/cli/src/runtime-dependencies.ts

sc dev

What it does:

• Starts the app from source
• Prints the CLI banner

How it is used:

sc dev
sc dev --port=4000

Flags:

| Flag | Meaning | | --- | --- | | --port=<number> | Sets PORT for the dev process |

What it solves:

• You can restart the app quickly while editing source files

Behavior:

• Uses nodemon when project.devServer is nodemon
• Uses tsx when project.devServer is tsx
• Refuses to run outside a Sculptor app root
• Suppresses the runtime banner by setting SCULPTOR_SUPPRESS_BANNER=1

sc start

What it does:

• Starts the app in production-style mode

How it is used:

sc start
sc start --port=4000
sc start --watch

Flags:

| Flag | Meaning | | --- | --- | | --port=<number> | Sets PORT for the process | | --watch | Forces the dev path instead of the built path |

Behavior:

• If dist/main.js exists and --watch is not set, it runs the built app
• If --watch is set, it behaves like sc dev
• If no build output exists, it falls back to tsx src/main.ts

What it solves:

• The same command can be used for production-style startup and local fallback startup

sc build

What it does:

• Runs TypeScript build for the current app

How it is used:

sc build

What it solves:

• Creates production JavaScript output from app source

Behavior:

• Only works inside a Sculptor app root
• Uses the app-local tsconfig.json

sc lint

What it does:

• Runs ESLint from the app root

How it is used:

sc lint

What it solves:

• Gives a single framework-aligned lint command

sc test

What it does:

• Runs the app test suite

How it is used:

sc test

Behavior:

• If src/tests/runner.spec.ts exists, runs vitest run src/tests/runner.spec.ts
• If the runner does not exist, falls back to vitest run

What it solves:

• You can keep a generated test registry while still having a standard test command

sc config

What it does:

• Reads, writes, and lists app config

How it is used:

sc config get logging
sc config set logging.dogMode=false
sc config list

Behavior:

• get reads a dot-path from the merged config
• set writes a dot-path assignment while preserving JSON formatting when possible
• list prints the flattened merged config
• sculptor supports the same command set as sc

sc install deps and sc i deps

What it does:

• Replays the standard Sculptor app dependency installation sequence
• Runs inside an existing Sculptor app root
• Helps recover after an interrupted npm i during setup

How it is used:

sc install deps
sc i deps

Behavior:

• Uses npm i for the app package.json dependencies first
• Installs the Sculptor runtime dependencies next
• Reinstalls the Sculptor CLI/config/router dev dependencies last
• Refuses to run outside a Sculptor app root

sc update

What it does:

• Updates globally installed Sculptor packages to their latest versions

How it is used:

sc update

Behavior:

• Works only outside a Sculptor app root
• Uses the active package manager when possible
• Updates the global Sculptor package set in one pass

sc generate and sc g

What it does:

• Generates framework resources in the current app

How it is used:

sc generate controller user
sc g c user

Supported kinds:

| Kind | Aliases | | --- | --- | | controller | c, controller | | service | s, service | | module | m, mo, module | | middleware | mw, middleware | | type | t, type | | route | r, route, resource |

Behavior:

• Refuses to run outside a Sculptor app root
• Controller generation is controller-first by default and can opt into paired functional route files with --functional
• Route generation always writes the paired functional route and handler files
• Rewrites the test registry when test generation is enabled

What it solves:

• Your app stays consistent as it grows

sc help

What it does:

• Prints help text

How it is used:

sc help
sc help generate
sc help controller
sc help module
sc help middleware
sc help type
sc help route

sc version

What it does:

• Prints the CLI version and the banner

How it is used:

sc version
sc v
sc -v
sc --v
sc --version

Full Flag Reference

Global flags and aliases

| Input | Meaning | | --- | --- | | -v | Print version | | --v | Print version | | --version | Print version | | version | Print version | | v | Print version | | -h | Print help | | --help | Print help |

sc new flags

| Flag | Meaning | | --- | --- | | --name | App name | | --version | Scaffold version | | --style | Routing style | | --decorator | Decorator routing shortcut | | --functional | Functional routing shortcut | | --hybrid | Hybrid routing shortcut | | --frameworkLock | Framework lock | | --frameworklock | Framework lock | | --framework-lock | Framework lock | | --dev-server | Dev server selection | | --devserver | Dev server selection | | --tsx | Dev server shortcut | | --nodemon | Dev server shortcut |

sc dev / sc start flags

| Flag | Meaning | | --- | --- | | --port | Sets the process port | | --watch | Only used by sc start |

sc generate flags

| Flag | Meaning | | --- | --- | | --functional | Use functional routing mode | | --with-routes | Alias for paired functional route generation | | --decorator | Use decorator routing mode | | --hybrid | Use hybrid routing mode | | --style | Explicitly set routing mode | | in <path> | Write files into a custom directory | | -i | Type generator creates *.interface.ts | | -interface | Type generator creates *.interface.ts | | -c | Type generator creates *.class.ts | | -class | Type generator creates *.class.ts | | -e | Type generator creates *.enum.ts | | -enum | Type generator creates *.enum.ts |

Generator Behavior

Controller generation

What it does:

• Writes *.controller.ts by default
• Pass --functional or --with-routes to also write paired *.route.ts and *.route.handler.ts files
• In functional-first app flows, the paired functional route files are the standard route shape

Examples:

sc generate controller user
sc g c user
sc g c user in src/app/users
sc g c in src/app/users
sc g c user --functional

If you use in <path>:

• the file location changes to that path
• the file name still follows the generator suffix
• if you do not provide a name, the CLI infers it from the last path segment
• the generated test file, when enabled, is written under src/tests

Service generation

What it does:

• Writes *.service.ts

Examples:

sc generate service user
sc g s user
sc g s user in src/app/services

Module generation

What it does:

• Writes *.module.ts

Examples:

sc generate module user
sc g m user
sc g mo user

Middleware generation

What it does:

• Writes *.middleware.ts

Examples:

sc generate middleware auth
sc g mw auth
sc g mw auth in src/app/middlewares

Type generation

What it does:

• Writes one of:
  • *.type.ts
  • *.interface.ts
  • *.class.ts
  • *.enum.ts

Examples:

sc g t
sc generate type user
sc g t user
sc generate type user -interface
sc g t user -i
sc generate type user -class
sc g t user -c
sc generate type user -enum
sc g t user -e

If you omit the name, the CLI falls back to index unless a custom output path lets it infer a name from the directory.

Route generation

What it does:

• Writes *.route.ts and *.route.handler.ts
• Uses the Sculptor functional router builder
• Generates a paired handler with try/catch and error middleware boilerplate

Examples:

sc generate route user
sc g r user
sc g r user in src/app/routes

Test Generation

Test generation is controlled by testing.generate in sculptor.json.

| Setting | Result | | --- | --- | | true | Matching *.spec.ts files are generated | | false | No new spec files are generated |

Generated spec names:

• user.controller.spec.ts
• user.service.spec.ts
• user.route.spec.ts
• auth.middleware.spec.ts

Default scaffold test files:

• src/tests/main.spec.ts
• src/tests/health.controller.spec.ts
• src/tests/health.route.spec.ts
• src/tests/registry.ts
• src/tests/runner.ts
• src/tests/runner.spec.ts

Test Harness Behavior

What it does:

• Discovers every *.spec.ts file under src/tests
• Writes src/tests/registry.ts
• Writes src/tests/runner.ts
• Writes src/tests/runner.spec.ts

How it is used:

• sc test runs the registry runner when it exists

What it solves:

• You do not have to manually keep your test suite entrypoint updated

App Root Rules

Only these commands work from outside a Sculptor app root:

• sc new
• sc help
• sc version
• sc update

sc install deps and sc i deps require a Sculptor app root.

Everything else requires sculptor.json in the current directory.

If you try to run a restricted command outside an app root, the CLI stops with a clear error.

CLI Banner Behavior

The version line in the banner is automatic.

If the package version changes, the banner version changes too.

Programmatic Use

import { runCli } from "@sculptor/cli";

await runCli(["node", "sc", "help"]);

Exports

@sculptor/cli re-exports:

• runCli
• resolveProjectMetadata
• scaffoldProject
• generateResourceFiles
• writeGeneratedFiles
• syncTestHarness
• the scaffold help strings

These generator helpers now resolve @sculptor/template-registry at runtime and can prompt to install it if the package is missing. Call them with await when using the package programmatically.

Package Scripts

• npm run cli runs the CLI source with tsx
• npm run build compiles the package
• npm run prepack builds before packaging

Runtime Boundaries

• @sculptor/template-registry is a runtime dependency, not a dev-only helper
• the CLI loads it lazily so global installs can recover cleanly when the package is missing
• future plugin/template loaders should follow the same pattern: detect, explain, recover, then retry
• publish @sculptor/template-registry before @sculptor/cli so global installs never see a missing runtime dependency during rollout

If You Only Remember One Thing

If you are inside a Sculptor app root, use:

sc dev
sc generate controller user
sc generate route user
sc config list
sc test

If you are outside an app root, only use:

sc new
sc help
sc version

License

MIT