AxilJS CLI Configuration
What the axil CLI reads in AxilJS 0.3.6: PORT and database variables from .env, axil.scaling.json fields, AXIL_WORKERS, tsconfig and colours.
The CLI has no config file of its own. Each command reads the project files it needs from the current directory, so run commands from the project root. This page lists everything the CLI reads.
| Source | Read by |
|---|---|
package.json | run (app name for Studio), deploy (name and version), doctor, install, generate (database and auth detection) |
tsconfig.json | run, build, test (rootDir and outDir) |
.env | run (PORT, database variables for Studio), migrate (connection) |
axil.scaling.json | capacity, deploy (and serve() from @axiljs/scale at runtime) |
src/ | run (watch), test (test files), capacity (multi-process readiness scan) |
Application configuration (typed config, loadEnv, defineConfig) is covered in Environment and Typed Config.
.env
axil run reads two things from .env (quotes are removed and inline comments stripped):
PORT: where the app listens (default 3000). Studio starts onPORT + 1.DATABASE_URLorDATABASE_FILENAME: passed to Studio so its database browser can connect. A URL starting withpostgresselects PostgreSQL,mysqlselects MySQL;DATABASE_FILENAMEselects SQLite.
axil migrate loads .env into the environment (variables already set win) and uses:
| Variable | Meaning |
|---|---|
DB_DRIVER | sqlite, postgres or mysql (optional; inferred otherwise) |
DATABASE_URL | Postgres or MySQL connection string |
DATABASE_FILENAME | SQLite file path (alias DB_FILE) |
These are the same variables the generated src/db/connection.ts reads.
tsconfig.json
axil run and axil test compile with the project's tsc and run the output, so tsconfig.json needs an outDir (generated projects use "rootDir": "./src", "outDir": "./dist"). axil run looks for the entry point at dist/main.js, dist/server.js or dist/index.js (or the same names under dist/src/). Keep "experimentalDecorators": true if you use the ORM or t* decorators.
axil.scaling.json
The scaling target and machine shape for a project, in the project root. Create a starter file with:
1{
2 "target": { "rps": 10000, "concurrentConnections": 20000, "p99Ms": 100 },
3 "vertical": { "workers": "auto", "maxConnectionsPerWorker": 10000, "memoryPerWorkerMb": 512 },
4 "horizontal": { "instances": { "min": 2, "max": 6 }, "instanceSize": { "cpus": 4, "memoryGb": 8 } },
5 "headroom": 0.3
6}| Field | Default | Meaning |
|---|---|---|
target.rps | not set | Peak requests per second the whole deployment must sustain |
target.concurrentConnections | not set | Peak open connections |
target.p99Ms | not set | p99 latency budget in ms |
vertical.workers | auto | Worker processes per instance; auto = one per CPU core |
vertical.maxConnectionsPerWorker | 10000 | Connections one worker may hold open |
vertical.memoryPerWorkerMb | 512 | Memory budget per worker (also its --max-old-space-size) |
vertical.shutdownTimeoutMs | 10000 | Grace period for in-flight requests on shutdown |
vertical.keepAliveTimeoutMs | Node's 5000 | Idle keep-alive timeout; behind a load balancer set it above the balancer's idle timeout (AWS ALB: 60 s) |
horizontal.instances | 1 | A fixed count, or { "min", "max" } autoscaling bounds |
horizontal.instanceSize | this machine | { "cpus", "memoryGb" } of one VM or pod |
headroom | 0.3 | Spare capacity kept above the target (0.3 = 30%) |
Invalid values (negative numbers, max below min, headroom outside 0 to 5, invalid JSON) are rejected with a message naming the field.
Who reads it:
axil capacitychecks whether the configuration can carry the target.axil deploysizes replicas, the autoscaler, pod resources,AXIL_WORKERSand the termination grace period from it.serve()from@axiljs/scaleapplies the vertical settings at runtime. See Scaling.
AXIL_WORKERS
AXIL_WORKERS overrides vertical.workers: auto or a number. One config file can then serve a laptop (AXIL_WORKERS=1 in .env for npm run dev) and a production machine (auto).
Terminal output
| Variable | Effect |
|---|---|
NO_COLOR (non-empty) | No colours |
FORCE_COLOR | Force colours on (0 or false forces them off) |
TERM=dumb | No colours |
CI | Disables clickable links |
Without a TTY, prompts return their defaults and spinners print single lines, so the CLI is safe to use in CI. axil create then needs a project name (or use --yes with a name).
Next steps
Was this page helpful?