CLI

AxilJS CLI Overview

The axil CLI in AxilJS 0.3.6: every command, the rail-style output, help screens, colour handling and how create, run, capacity and deploy fit together.

5 min readUpdated DocumentationEdit this page
On this page8

@axiljs/cli provides the axil command (also installed as axiljs). It creates projects from templates, runs the dev server with hot reload and Studio, generates code, runs migrations and tests, plans capacity, writes deployment files and inspects the semantic decorator catalog. The current release is 0.3.6.

Terminal
❯npx @axiljs/cli create # no install needed
❯npm install -g @axiljs/cli # or install the axil binary globally
❯axil --version # @axiljs/cli v0.3.6

Commands

axil --help groups the commands by workflow:

GroupCommandWhat it does
Projectaxil create [name]Create a new project: template picker or custom stack
Projectaxil generate <kind> <name> (alias g)Generate a module, controller, service, entity or migration
Projectaxil install [packages…] (alias i)Add packages to package.json and run npm install
Developaxil runDevelopment server with hot reload + Studio
Developaxil test [pattern]Compile and run *.test.ts / *.spec.ts with @axiljs/testing
Developaxil doctorDiagnose the project
Databaseaxil migrate [up|down|status]Run @axiljs/orm migrations
Shipaxil buildType-check and compile TypeScript for production
Shipaxil capacity (alias cap)Check whether this machine / deployment can carry the scaling target
Shipaxil deployGenerate a Dockerfile, Kubernetes manifests and .dockerignore
Inspectaxil decorator <sub> (alias dec)List, search, inspect and check semantic decorators
Inspectaxil verify [pattern]Check which decorators the runtime enforces, flag unwired classes and run the tests with intent checks in enforce mode (new in 0.3.5)

Global options: -h, --help and -v, --version. A mistyped command or flag gets a suggestion, for example Unknown command 'crate' — did you mean 'create'?.

Details: Project Commands, Capacity, Decorator Commands, Verify.

Help

Terminal
❯axil --help # banner, quick-start card, all commands
❯axil create --help # one command: usage, options, details, examples
❯axil help deploy # same as axil deploy --help

Every command accepts --help / -h. Command help lists each flag with its accepted values, and axil create --help also lists all templates by category.

The output style

All CLI output shares one look in the AxilJS brand colours: the orange-to-red gradient of the logo (#FD8702 to #ED1010). Help screens open with a gradient ▲ AXIL banner and a version badge. Command flows are drawn on a rail:

Output
TXT
  ┌  axil deploy  Generate Docker + Kubernetes files
  │
  ◇  Using axil.scaling.json  instances 3–10, 4 CPU / 8 GB pods
  ◇  Deployment files generated  deploy/
  │
  └  Next steps
     npm run build
     docker build -f deploy/Dockerfile -t my-api .
     docker run -p 3009:3009 my-api
SymbolMeaning
┌A command starts (its name and a one-line summary)
◇A step succeeded
●Information
▲Warning
■Error
◆A section heading or the final result
└The flow ends: next steps, a failure, or the closing line

Results such as the create summary, the axil capacity Plan and the axil doctor Diagnostics are shown as cards on the rail. Long-running steps (npm install, compilation, load tests) show a spinner on interactive terminals and a single line in CI logs.

Terminal compatibility

  • Colours follow NO_COLOR, FORCE_COLOR, TERM=dumb and whether stdout is a TTY. Without truecolor support, the brand colour falls back to yellow.
  • On legacy Windows consoles the Unicode symbols fall back to ASCII (+, |, *, o, !, x). Windows Terminal, VS Code, JetBrains terminals and most Unix terminals get the Unicode set.
  • Links are clickable in terminals that support OSC 8 (Windows Terminal, VS Code, iTerm2, WezTerm, ghostty).
  • axil decorator graph prints pure JSON and axil --version prints only @axiljs/cli vX.Y.Z, so both are safe to pipe.

Interactive vs non-interactive

On a terminal, axil create asks for anything you did not pass (name, template, database, features, confirmation). Without a TTY (CI, pipes) or with --yes, every prompt takes its default and a project name is required. Ctrl+C (or esc outside a search) cancels a prompt and exits with code 130.

Terminal
❯axil create # fully interactive
❯axil create my-api --template rest-api # skips the picker, still confirms
❯axil create my-api --yes --db=sqlite # no prompts at all

A typical workflow

Terminal
❯npx @axiljs/cli create my-api --template rest-api
❯cd my-api
❯cp .env.example .env # PowerShell: Copy-Item .env.example .env
❯npm test # axil test: the template's own tests
❯npm run dev # axil run: app + Studio on PORT + 1
❯axil generate module orders # grow the project
❯axil verify # decorators enforced? tests pass in intent-enforce mode?
❯axil build # type-check + compile to dist/
❯axil capacity --init # write axil.scaling.json
❯axil capacity # can this setup carry the target?
❯axil deploy # Dockerfile + Kubernetes, sized from axil.scaling.json

Run the CLI from a project

Generated projects list @axiljs/cli as a devDependency, so inside a project npx axil <command> uses the project's copy and the npm scripts (npm run dev, npm test, npm run migrate) work without a global install.

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