Skip to content
GitHub

Strutvane 0.2 is still being built. These pages describe how it will work; anything marked "Coming in 0.2" doesn't exist yet. Release notes and support policy.

Strut Console

View as Markdownllms.txt

node strut is your app’s command line: Strutvane’s php artisan. You use it to create files (make:migration), change the database (migrate), look inside the app (route:list, about) and run your own commands. This page explains how it works and how to add commands of your own. Every built-in command is listed in the CLI Reference.

From your project folder:

Terminal window
node strut list

What you’ll see (shortened):

Strutvane console. Usage: node strut <command> [arguments] [options]
Available commands:
about Show the app name, environment, database, routes and providers
serve Serve the application on the local HTTP server
make
make:controller Create a new controller class
make:migration Create a migration (and the model, for create_*_table)
model
model:show Show a model's columns, casts and API behaviour
route
route:list List every registered route
Run `node strut help <command>` for details.

node strut with no command does the same as node strut list, and help is an alias for it.

strut.js is a small file in your project’s root folder:

strut.js
// The project's command line, like Laravel's `artisan`. Run it from this folder:
//
// node strut list every command
// node strut route:list show the routes
// node strut help make:controller
//
// It is a plain .js file so `node strut` works the same in PowerShell, cmd and bash.
import { runConsole } from '@strutvane/framework/console'
import app from './bootstrap/app.ts'
process.exitCode = await runConsole(app, process.argv.slice(2))

Why a plain .js file run with node? It works the same in PowerShell, cmd, bash and zsh: there’s no .cmd or .ps1 wrapper, no PowerShell execution-policy prompt, no -- rule, and no clash with a shell alias (0.1’s sv clashed with PowerShell’s built-in sv). npx strutvane <command> does exactly the same.

What happens when you type a command:

  1. runConsole finds the command (core commands, then your app’s and your packages’, which may replace a core one with the same name).
  2. It checks the arguments and options against the command’s declaration.
  3. It boots the app, the same boot a request gets: .env and config checked, providers run, routes compiled. Commands that only write files (make:*) skip this step, so they work before .env exists.
  4. It runs the command inside the app, so config(), route() and models work.
  5. It exits with the command’s exit code.
Terminal window
node strut help make:controller
node strut make:controller --help # the same

What you’ll see:

Create a new controller class
Usage: node strut make:controller <name> [options]
Arguments:
name The class name, ending in Controller (PostController) (required)
Options:
-r, --resource Write all 7 resource actions (index, create, store, show, edit, update, destroy)
--api Write the 5 API actions (no create/edit form pages)
-m, --model=<value> Inherit the API actions from ResourceController for this model
--force Overwrite the file if it exists
Examples:
node strut make:controller ReportController
node strut make:controller PostController --resource
node strut make:controller PostController --api
node strut make:controller PostController --model=Post

Options with a value are written --model=Post or --model Post; short forms are -m Post.

Strutvane never answers a typo with a stack trace:

Terminal window
node strut rout:list
✖ There is no "rout:list" command.
→ Did you mean `node strut route:list`?

Every developer mistake prints what happened (✖) and how to fix it (→):

✖ make:controller has no --resouce option.
→ Did you mean --resource?
✖ make:migration needs <name>.
→ Example: node strut make:migration <name> (more: node strut help make:migration)
Code Means
0 Success
1 A mistake you can fix (unknown command, bad option, a friendly error)
3 migrate couldn’t reach the database (so the installer can offer Retry)
anything else What your own command returned

Scripts and CI can check them: node strut route:list || echo "the app doesn't boot".

Inspection commands print JSON for scripts and AI agents:

Terminal window
node strut route:list --json
node strut about --json
node strut model:show Post --json

What you’ll see (for about --json, shortened):

{
"application": { "name": "My App", "environment": "local", "debug": true, "url": "http://localhost:3000" },
"runtime": { "node": "v24.21.0", "platform": "linux" },
"http": { "routes": 15, "namedRoutes": 14 }
}

about never prints secrets: no keys, no passwords, no full database URLs, so it’s safe to paste into a bug report.

With Docker Without Docker
node strut migrate Forwarded into the app container for you Runs on your computer
node strut shell A shell inside the app container (bash, or sh) Not needed
node strut npm install x npm inside the container (also npx and node) Use npm install x
Arguments Passed through exactly, with no shell (a&b, $(…), %PATH% arrive as typed) The same
Exit codes Passed back from the container —

The forwarder in strut.js needs Node on your computer; nothing else does. See Docker.

A command is an object made with defineCommand(). Arguments and options are data, so help, validation and the option types all come from one place.

app/console/inspire.command.ts
import { defineCommand } from '@strutvane/framework/console'
export const inspire = defineCommand({
name: 'inspire',
description: 'Print a quote',
run({ output }) {
output.line('Simplicity is the soul of efficiency.')
},
})

Register it in bootstrap/app.ts (Laravel’s routes/console.php):

bootstrap/app.ts
import { inspire } from '../app/console/inspire.command.ts'
export default Application.configure({ basePath: dirname(import.meta.dirname) })
// …the rest of your chain…
.withCommands([inspire])
.create()
Terminal window
node strut inspire

What you’ll see:

Simplicity is the soul of efficiency.
app/console/posts-publish.command.ts
import { defineCommand } from '@strutvane/framework/console'
import { Post } from '../models/post.ts'
export const publishPost = defineCommand({
name: 'posts:publish',
description: 'Publish a post by its slug',
arguments: [{ name: 'slug', description: 'The post to publish (its slug)', required: true }],
options: {
dryRun: { type: 'boolean', short: 'd', description: 'Show what would change, change nothing' },
note: { type: 'string', description: 'A note for the log' },
},
help: ['Examples:', ' node strut posts:publish hello-world', ' node strut posts:publish hello-world --dryRun'],
async run({ args, options, output, now }) {
const post = await Post.query().where('slug', args[0] ?? '').first()
if (post === undefined) {
output.error(` ✖ No post has the slug "${args[0] ?? ''}".`)
return 1
}
if (options.dryRun) {
output.line(` Would publish "${post.title}".`)
return 0
}
await post.update({ status: 'published' })
output.line(` at ${now().toISOString()}`)
output.line(` Published "${post.title}"${options.note === undefined ? '' : ` (${options.note})`}.`)
return 0
},
})

Inside run:

You get Type
args The positional arguments, as strings
options.dryRun boolean (a boolean option)
options.note string | undefined (a string option)
output.line(text) / output.error(text) Write to stdout / stderr
now() The current time (fixed in tests)
app The booted application

The option types come from the declaration, so options.nope doesn’t compile. Return a number to set the exit code; returning nothing means 0.

Terminal window
node strut posts:publish hello-world --note "launch day"

What you’ll see:

at 2026-11-14T10:00:00.000Z
Published "Hello World" (launch day).

Set needsBoot: false when the command doesn’t need the app booted (it only writes files). It then runs even when .env is incomplete, like the make:* commands.

A package adds its commands from its service provider:

node_modules/@acme/billing/src/billing.provider.ts
import { ServiceProvider, type Application } from '@strutvane/framework'
import { billingSync } from './billing-sync.command.ts'
export class BillingServiceProvider extends ServiceProvider {
override register(app: Application): void {
app.addCommand(billingSync)
}
}

An app or package command with the same name as a core command replaces it, on purpose. See Service Providers.

runConsole returns the exit code instead of exiting, and takes an output buffer and a fixed clock:

tests/console/inspire.test.ts
import { randomBytes } from 'node:crypto'
import { expect, test } from 'vitest'
import { runConsole } from '@strutvane/framework/console'
import { createApp } from '../../bootstrap/app.ts'
test('inspire prints a quote', async () => {
const lines: string[] = []
const output = { line: (text = '') => lines.push(text), error: (text: string) => lines.push(text) }
const app = createApp({ APP_ENV: 'testing', APP_KEY: `base64:${randomBytes(32).toString('base64')}`, DB_CONNECTION: 'sqlite' })
const code = await runConsole(app, ['inspire'], { output, now: () => new Date('2026-11-14T10:00:00Z') })
expect(code).toBe(0)
expect(lines).toEqual(['Simplicity is the soul of efficiency.'])
})

What you’ll see with npm test: the test passes.

In the prototype, a cold node strut route:list takes 0.75 to 1.0 seconds, most of it loading TypeScript files. Loading command modules only when they run, and shipping the framework as compiled JavaScript, are the planned fixes; the target is under 300 ms (unverified until built). See Optimization.

Error: Cannot find module 'C:\Users\you\strut'

Why: strut.js is in your project folder, and you ran node strut from somewhere else. Fix: cd my-app first.

Why: it isn’t registered. Fix: add it to .withCommands([...]) in bootstrap/app.ts (or app.addCommand() in a provider’s register()).

My command fails with environment errors, but it only writes a file

Section titled “My command fails with environment errors, but it only writes a file”
✖ The app can't start: 1 environment variable needs attention.
- APP_KEY is required (a text value); add it to .env (read in config/app.ts)
→ Fix the values in .env (see .env.example for every key) and start again.

Why: commands boot the app by default, and boot checks .env. Fix: add needsBoot: false to a command that doesn’t need the app.

sv or strut “is not recognized as a command”

Section titled “sv or strut “is not recognized as a command””

Why: there’s no global strut command; it’s always node strut (or npx strutvane). sv was 0.1’s name. Fix: node strut <command>.

Why: PowerShell and bash quote differently, and some characters (&, |, $) mean something to the shell before Node sees them. Fix: wrap such arguments in single quotes in PowerShell ('a&b') and bash alike. node strut passes them on unchanged, also into Docker.