Strut Console
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.
The smallest example
Section titled “The smallest example”From your project folder:
node strut listWhat 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.
How node strut works
Section titled “How node strut works”strut.js is a small file in your project’s root folder:
// 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:
runConsolefinds the command (core commands, then your app’s and your packages’, which may replace a core one with the same name).- It checks the arguments and options against the command’s declaration.
- It boots the app, the same boot a request gets:
.envand config checked, providers run, routes compiled. Commands that only write files (make:*) skip this step, so they work before.envexists. - It runs the command inside the app, so
config(),route()and models work. - It exits with the command’s exit code.
Getting help
Section titled “Getting help”node strut help make:controllernode strut make:controller --help # the sameWhat 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=PostOptions with a value are written --model=Post or --model Post; short forms are -m Post.
Typos and mistakes
Section titled “Typos and mistakes”Strutvane never answers a typo with a stack trace:
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)Exit codes
Section titled “Exit codes”| 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".
Machine-readable output: --json
Section titled “Machine-readable output: --json”Inspection commands print JSON for scripts and AI agents:
node strut route:list --jsonnode strut about --jsonnode strut model:show Post --jsonWhat 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 or without
Section titled “With Docker or without”| 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.
Writing your own command
Section titled “Writing your own command”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.
Small: a command with no input
Section titled “Small: a command with no input”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):
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()node strut inspireWhat you’ll see:
Simplicity is the soul of efficiency.Typical: arguments, options and the app
Section titled “Typical: arguments, options and the app”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.
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).Commands that only write files
Section titled “Commands that only write files”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.
Advanced: a command from a package
Section titled “Advanced: a command from a package”A package adds its commands from its service provider:
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.
Testing a command
Section titled “Testing a command”runConsole returns the exit code instead of exiting, and takes an output buffer and a fixed clock:
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.
Coming next
Section titled “Coming next”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.
Common mistakes
Section titled “Common mistakes”“Cannot find module ‘…\strut’”
Section titled ““Cannot find module ‘…\strut’””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.
My command isn’t in node strut list
Section titled “My command isn’t in node strut list”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>.
PowerShell swallows my quotes
Section titled “PowerShell swallows my quotes”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.
Next steps
Section titled “Next steps”- CLI Reference: every built-in command.
- Prompts: asking questions in your commands.
- Service Providers: commands from packages.
- Task Scheduling: running commands on a schedule.