CLI

AxilJS Project Commands

Reference for every axil project command in AxilJS 0.3.6: create, generate, migrate, run, test, build, install, deploy, doctor.

8 min readUpdated DocumentationEdit this page
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

Terminal
❯axil create [name] [options]

Creates a new project in ./<name>, writes the files, runs npm install and prints numbered next steps.

OptionDescription
-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, --yesAccept defaults for every option not given as a flag (no prompts)
--db <driver>none (default), sqlite, postgres, mysql
--auth / --no-authJWT + RBAC auth (default: on)
--aiInclude the AI platform (default: off)
--wsInclude WebSocket support (default: off)
--queueInclude Queue and Scheduler (default: off)
--skip-installDo not run npm install
--forceAllow creating into an existing non-empty directory

Interactive flow

On a terminal, anything you did not pass is asked for in four steps:

  1. 1/4 Project name: only when no name was given. Letters, numbers, ., -, _; it cannot start with . or -.
  2. 2/4 Template picker: categories Start, APIs, Realtime, Background, AI, Production and Custom. ↑ ↓ move (and flow across categories at the ends), ← → or tab switch category, space / enter select, / searches every category, esc leaves the search or cancels.
  3. 3/4 Database and features: only for Custom. A database select, then one multi-select for Authentication, WebSocket, Queue and AI platform.
  4. 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 --yes there are no prompts and a name is required.
  • --template cannot be combined with --db, --auth, --ai, --ws or --queue. Giving any of those flags without --template skips 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, typescript and @types/node as devDependencies, so axil run can start Studio and npm test works immediately. Sibling @axiljs/* packages are pinned to the ^0.3.0 minor line.
  • If scaffolding or npm install fails, the CLI says where the partial project was left so you can remove it before retrying.
Terminal
❯axil create my-api
❯axil create my-api --yes
❯axil create my-api --db=sqlite --auth --ws --skip-install
❯axil create my-api -y --db postgres --no-auth --queue
❯axil create shop --template rest-api
❯axil create chat -t realtime-chat --skip-install

axil generate

Terminal
❯axil generate <module|controller|service|entity|migration> <name> [options]
❯axil g <kind> <name>

Generates files in the layout axil create uses:

KindFiles
modulesrc/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
controllersrc/modules/<name>/controllers/<name>.controller.ts
servicesrc/modules/<name>/services/<name>.service.ts
entitysrc/modules/<name>/entities/<name>.entity.ts
migrationsrc/migrations/<NNN>_<name>.ts (the next free number)
OptionDescription
--forceOverwrite files that already exist (otherwise they are skipped with a warning)
--db <driver>Database driver for the templates (default: detected from package.json)
--authProtect the list route with authenticate() (default: detected from package.json)
Terminal
❯axil generate module products
❯axil g controller orders
❯axil g entity product
❯axil g migration add_price_to_products

Register a generated controller in src/main.ts: new ProductsController().register(app).

axil migrate

Terminal
❯axil migrate [up|down|status] [--dir <path>]

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:

VariableMeaning
DB_DRIVERsqlite, postgres or mysql (optional; inferred otherwise)
DATABASE_URLpostgres://… or mysql://… connection string
DATABASE_FILENAMESQLite 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.

Terminal
❯axil migrate
❯axil migrate status
❯axil migrate down
❯axil migrate up --dir=dist/migrations

axil run

Terminal
❯axil run

The development server. It takes no options.

  1. Checks for package.json, tsconfig.json and src/.
  2. Compiles with tsc --incremental --noEmitOnError.
  3. Starts the first entry it finds: dist/main.js, dist/server.js, dist/index.js, or the same names under dist/src/.
  4. Starts Studio on the app port + 1. The app port is PORT from .env (default 3000).
  5. Watches src/ for .ts / .tsx changes, recompiles and restarts the app. Compile errors are printed and the running app is left alone until the next save.
Output
TXT
  12:04:31 ✔ Restarted in 320ms  src/app.ts · #1

If @axiljs/studio cannot be found (project node_modules first), axil run keeps going without it and prints:

Output
TXT
  → Studio skipped  @axiljs/studio not installed: npm install -D @axiljs/studio

Projects 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

Terminal
❯axil test [pattern]

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.

Terminal
❯axil test
❯axil test users

axil build

Terminal
❯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

Terminal
❯axil install [packages…] [-D]
❯axil i @axiljs/queue

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

Terminal
❯axil deploy [--port <n>] [--replicas <n>] [--force]

Writes deploy/Dockerfile, deploy/deployment.yaml (Deployment, Service, and an optional HorizontalPodAutoscaler), deploy/deploy.sh and a .dockerignore in the project root.

OptionDescription
--port <n>Container port (default: 3000)
--replicas <n>Kubernetes replicas (default: instances.min from axil.scaling.json, else 3)
--forceOverwrite 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-alpine Dockerfile: npm ci + npm run build, then a production stage with npm ci --production and dist/. It sets NODE_ENV=production, PORT and HOST=0.0.0.0 (containers must listen on all interfaces) and runs node dist/main.js.
  • Environment NODE_ENV, PORT and HOST=0.0.0.0 in the manifest.
  • Liveness probe on /health/live and readiness probe on /health/ready. Make sure your app serves both (the microservice, live-dashboard and high-scale-api templates 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 fieldSource
replicashorizontal.instances.min (unless --replicas is given)
HorizontalPodAutoscalerAdded 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 envThe 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
terminationGracePeriodSecondsvertical.shutdownTimeoutMs rounded up to seconds, + 5
DockerfileAlso 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.

Terminal
❯axil deploy
❯axil deploy --port=8080 --replicas=2
❯axil deploy --force

Then build and run the image from the project root:

Terminal
❯npm run build
❯docker build -f deploy/Dockerfile -t my-api .
❯docker run -p 3000:3000 my-api

deploy/deploy.sh does the build with the version tag from package.json and runs kubectl apply -f deploy/deployment.yaml.

axil doctor

Terminal
❯axil doctor

Runs quick checks and shows them in a Diagnostics card with a passed/total count:

CheckPasses when
Node.js versionNode.js 18 or newer is running (AxilJS packages themselves need 20+)
TypeScriptnpx tsc --version works
package.json, tsconfig.json, src/main.tsThe file exists
@axiljs/core dependencyListed in dependencies or devDependencies
Lock filepackage-lock.json, axil.lock or @axiljs.lock exists
.env protected.gitignore mentions .env

Version and help

Terminal
❯axil --version # @axiljs/cli v0.3.6
❯axil --help
❯axil <command> --help

Was this page helpful?

Help improve the documentation

AxilJS is open source and documentation improvements are welcome.

AxilJS DocumentationMIT License · Built by SyntaxilitY