CLI

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.

4 min readUpdated DocumentationEdit this page
On this page6

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.

SourceRead by
package.jsonrun (app name for Studio), deploy (name and version), doctor, install, generate (database and auth detection)
tsconfig.jsonrun, build, test (rootDir and outDir)
.envrun (PORT, database variables for Studio), migrate (connection)
axil.scaling.jsoncapacity, 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 on PORT + 1.
  • DATABASE_URL or DATABASE_FILENAME: passed to Studio so its database browser can connect. A URL starting with postgres selects PostgreSQL, mysql selects MySQL; DATABASE_FILENAME selects SQLite.

axil migrate loads .env into the environment (variables already set win) and uses:

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

Terminal
❯axil capacity --init
JSON
JSON
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}
FieldDefaultMeaning
target.rpsnot setPeak requests per second the whole deployment must sustain
target.concurrentConnectionsnot setPeak open connections
target.p99Msnot setp99 latency budget in ms
vertical.workersautoWorker processes per instance; auto = one per CPU core
vertical.maxConnectionsPerWorker10000Connections one worker may hold open
vertical.memoryPerWorkerMb512Memory budget per worker (also its --max-old-space-size)
vertical.shutdownTimeoutMs10000Grace period for in-flight requests on shutdown
vertical.keepAliveTimeoutMsNode's 5000Idle keep-alive timeout; behind a load balancer set it above the balancer's idle timeout (AWS ALB: 60 s)
horizontal.instances1A fixed count, or { "min", "max" } autoscaling bounds
horizontal.instanceSizethis machine{ "cpus", "memoryGb" } of one VM or pod
headroom0.3Spare 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 capacity checks whether the configuration can carry the target.
  • axil deploy sizes replicas, the autoscaler, pod resources, AXIL_WORKERS and the termination grace period from it.
  • serve() from @axiljs/scale applies 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

VariableEffect
NO_COLOR (non-empty)No colours
FORCE_COLORForce colours on (0 or false forces them off)
TERM=dumbNo colours
CIDisables 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?

Help improve the documentation

AxilJS is open source and documentation improvements are welcome.

AxilJS DocumentationMIT License · Built by SyntaxilitY