AxilJS Project Commands
Reference for every axil project command in AxilJS 0.3.6: create, generate, migrate, run, test, build, install, deploy, doctor.
On this page14
Every command below accepts --help / -h. Run them from the project root (the folder with package.json), except axil create. For axil capacity see Capacity; for axil decorator see Decorator Commands.
axil create
Creates a new project in ./<name>, writes the files, runs npm install and prints numbered next steps.
| Option | Description |
|---|---|
-t, --template <id> | Start from a template: minimal, rest-api, realtime-chat, background-jobs, ai-assistant, saas-api, microservice, webhook-receiver, live-dashboard, high-scale-api |
-y, --yes | Accept defaults for every option not given as a flag (no prompts) |
--db <driver> | none (default), sqlite, postgres, mysql |
--auth / --no-auth | JWT + RBAC auth (default: on) |
--ai | Include the AI platform (default: off) |
--ws | Include WebSocket support (default: off) |
--queue | Include Queue and Scheduler (default: off) |
--skip-install | Do not run npm install |
--force | Allow creating into an existing non-empty directory |
Interactive flow
On a terminal, anything you did not pass is asked for in four steps:
- 1/4 Project name: only when no name was given. Letters, numbers,
.,-,_; it cannot start with.or-. - 2/4 Template picker: categories Start, APIs, Realtime, Background, AI, Production and Custom.
↑↓move (and flow across categories at the ends),←→ortabswitch category,space/enterselect,/searches every category,escleaves the search or cancels. - 3/4 Database and features: only for Custom. A database select, then one multi-select for Authentication, WebSocket, Queue and AI platform.
- 4/4 Confirm: a summary card (template, category, packages, port and location; or the custom stack), then
Create project?.
Rules
- Without a TTY or with
--yesthere are no prompts and a name is required. --templatecannot be combined with--db,--auth,--ai,--wsor--queue. Giving any of those flags without--templateskips the picker and creates a Custom project.- An unknown template id fails with a suggestion, for example
Unknown template "rest". Did you mean "rest-api"?. - Every new project gets
@axiljs/cli,@axiljs/studio,@axiljs/testing,typescriptand@types/nodeas devDependencies, soaxil runcan start Studio andnpm testworks immediately. Sibling@axiljs/*packages are pinned to the^0.3.0minor line. - If scaffolding or
npm installfails, the CLI says where the partial project was left so you can remove it before retrying.
axil generate
Generates files in the layout axil create uses:
| Kind | Files |
|---|---|
module | src/modules/<name>/controllers/<name>.controller.ts, src/modules/<name>/services/<name>.service.ts, and src/migrations/<NNN>_create_<table>.ts when a database is configured |
controller | src/modules/<name>/controllers/<name>.controller.ts |
service | src/modules/<name>/services/<name>.service.ts |
entity | src/modules/<name>/entities/<name>.entity.ts |
migration | src/migrations/<NNN>_<name>.ts (the next free number) |
| Option | Description |
|---|---|
--force | Overwrite files that already exist (otherwise they are skipped with a warning) |
--db <driver> | Database driver for the templates (default: detected from package.json) |
--auth | Protect the list route with authenticate() (default: detected from package.json) |
Register a generated controller in src/main.ts: new ProductsController().register(app).
axil migrate
Runs the @axiljs/orm MigrationRunner. up (the default) applies pending migrations, down rolls back the last batch, status shows applied and pending ones.
It loads .env from the project directory (variables already set in the environment win) and connects with:
| Variable | Meaning |
|---|---|
DB_DRIVER | sqlite, postgres or mysql (optional; inferred otherwise) |
DATABASE_URL | postgres://… or mysql://… connection string |
DATABASE_FILENAME | SQLite file (DB_FILE is accepted as an alias) |
Migrations default to src/migrations. Loading .ts migrations directly needs Node.js 22.18 or newer (type stripping); when Node cannot load .ts files and dist/migrations exists, dist/migrations is used. --dir points somewhere else.
axil run
The development server. It takes no options.
- Checks for
package.json,tsconfig.jsonandsrc/. - Compiles with
tsc --incremental --noEmitOnError. - Starts the first entry it finds:
dist/main.js,dist/server.js,dist/index.js, or the same names underdist/src/. - Starts Studio on the app port + 1. The app port is
PORTfrom.env(default 3000). - Watches
src/for.ts/.tsxchanges, recompiles and restarts the app. Compile errors are printed and the running app is left alone until the next save.
12:04:31 ✔ Restarted in 320ms src/app.ts · #1If @axiljs/studio cannot be found (project node_modules first), axil run keeps going without it and prints:
→ Studio skipped @axiljs/studio not installed: npm install -D @axiljs/studioProjects created with axil create 0.3.3 or later already include it. Ctrl+C stops Studio and the app (SIGTERM, then SIGKILL after 3 seconds).
axil test
Finds *.test.ts, *.spec.ts, *.test.js and *.spec.js under src/ and tests/, optionally filtered by a substring of the path. TypeScript tests inside rootDir are compiled first with tsc -p tsconfig.json and the compiled files are run, so ESM imports ending in .js resolve. Tests run on the project's own @axiljs/testing. The exit code is 1 when a test fails, a file fails to load, or compilation fails.
axil build
Runs tsc --noEmit (type check), then tsc, and reports the size of dist/. Any error stops the build with exit code 1. Start the result with node dist/main.js (or npm start).
axil install
With package names, adds them to dependencies (or devDependencies with -D / --dev) in package.json, then runs npm install. A bare name is saved as latest, an exact version such as @axiljs/queue@0.3.6 as ^0.3.6, and tags or ranges as given. Without names it just runs npm install.
axil deploy
Writes deploy/Dockerfile, deploy/deployment.yaml (Deployment, Service, and an optional HorizontalPodAutoscaler), deploy/deploy.sh and a .dockerignore in the project root.
| Option | Description |
|---|---|
--port <n> | Container port (default: 3000) |
--replicas <n> | Kubernetes replicas (default: instances.min from axil.scaling.json, else 3) |
--force | Overwrite without warnings, including an existing .dockerignore |
Existing deploy/ files are overwritten with a warning; .dockerignore is only created when missing (or replaced with --force). Image and resource names come from package.json name, lowercased and made DNS-safe (@org/api becomes org-api).
Always generated
- A two-stage
node:20-alpineDockerfile:npm ci+npm run build, then a production stage withnpm ci --productionanddist/. It setsNODE_ENV=production,PORTandHOST=0.0.0.0(containers must listen on all interfaces) and runsnode dist/main.js. - Environment
NODE_ENV,PORTandHOST=0.0.0.0in the manifest. - Liveness probe on
/health/liveand readiness probe on/health/ready. Make sure your app serves both (themicroservice,live-dashboardandhigh-scale-apitemplates do). - A Service on port 80 targeting the container port.
Sized from axil.scaling.json
When the project root has an axil.scaling.json (see Capacity), axil deploy prints Using axil.scaling.json and sizes the deployment from it:
| Manifest field | Source |
|---|---|
replicas | horizontal.instances.min (unless --replicas is given) |
| HorizontalPodAutoscaler | Added when instances.max is above the replica count: maxReplicas = instances.max, CPU target = 100 / (1 + headroom) % (77% with the default headroom of 0.3) |
Pod resources (requests = limits) | horizontal.instanceSize: cpus and memoryGb as Gi (only when instanceSize is set) |
AXIL_WORKERS env | The pod's CPU count when vertical.workers is auto (inside a CPU-limited pod auto would see the node's cores), otherwise the configured number |
terminationGracePeriodSeconds | vertical.shutdownTimeoutMs rounded up to seconds, + 5 |
| Dockerfile | Also copies axil.scaling.json into the image, so serve() applies the worker, connection and shutdown limits in the container |
An invalid axil.scaling.json stops the command with the reason. Without the file you get 3 replicas and no autoscaler, resources, AXIL_WORKERS or grace period.
Then build and run the image from the project root:
deploy/deploy.sh does the build with the version tag from package.json and runs kubectl apply -f deploy/deployment.yaml.
axil doctor
Runs quick checks and shows them in a Diagnostics card with a passed/total count:
| Check | Passes when |
|---|---|
| Node.js version | Node.js 18 or newer is running (AxilJS packages themselves need 20+) |
| TypeScript | npx tsc --version works |
package.json, tsconfig.json, src/main.ts | The file exists |
@axiljs/core dependency | Listed in dependencies or devDependencies |
| Lock file | package-lock.json, axil.lock or @axiljs.lock exists |
.env protected | .gitignore mentions .env |
Version and help
Was this page helpful?