Introduction

Overview

The AntelopeJS CLI (ajs) provides a single command-line interface for every stage of the development lifecycle. You use it to create projects, manage modules, run development servers, produce build artifacts, and configure global settings.

Installation

Install the CLI globally with your preferred package manager:

npm install -g @antelopejs/core

yarn global add @antelopejs/core

pnpm add -g @antelopejs/core

After installation, the ajs command is available in your terminal. Verify it works by checking the version:

ajs --version

Command Structure

Every CLI invocation follows the same pattern:

ajs <command> <subcommand> [arguments] [options]

The CLI organizes its functionality into these top-level commands:

Each top-level command contains subcommands that perform specific tasks. For example, ajs project dev runs the project in development mode, while ajs project modules add adds modules to it.

Global Options

These options are accepted by every command, anywhere on the command line:

By default --verbose enables TRACE-level logging for all channels. To scope it to specific channels, pass a comma-separated list after an equals sign, for example --verbose=cli.command,resolution. Only --verbose=<channels> takes a channel list: a bare --verbose never reads the next argument, so ajs --verbose project dev runs project dev with every channel. A verbose run also prints stack traces and the full output of the commands ajs runs when something fails.

-q, --quiet (or ANTELOPEJS_QUIET=1) keeps a run to what matters in scripts: results on stdout, warnings and errors on stderr, and the exit code. Progress lines, information messages, summaries, next steps and the update notice are left out.

Colors are only used on an interactive terminal. --no-color and a non-empty NO_COLOR always turn them off; otherwise FORCE_COLOR=1 turns them on and FORCE_COLOR=0 off. CI=true and TERM=dumb turn them off too. The same rules apply to the log lines of ajs project dev, build and start.

Getting Help

Running ajs without arguments prints the top-level help on stdout and exits with code 0, and so does a command group run without a subcommand, such as ajs project. An unknown subcommand is a usage error (exit code 2). It lists the commands, the official plugins and a few examples:

AntelopeJS CLI v1.10.3

Usage: ajs [options] [command]

Build modular Node.js applications from explicit interfaces.

Options:
  -v, --version             Print the version
  --verbose [=channels]     Print TRACE logs and full error details, optionally
                            for some log channels only (comma-separated)
                            (preset: "*", env: ANTELOPEJS_VERBOSE)
  -q, --quiet               Print only results, warnings and errors: no
                            progress, information or summaries (env:
                            ANTELOPEJS_QUIET)
  --no-color                Disable colors (also NO_COLOR=1)
  -h, --help                Show help for a command

Commands:
  project                   Create, run, build and configure projects
  module                    Create and test modules
  config                    Show or change CLI settings
  update [plugin]           Update the CLI and its global plugins
  plugins|plugin [options]  List official plugins
  help [command]            Show help for a command

Plugins:
  dms        DMS frontend commands (@antelopejs/dms-frontend)
  Resolved from the nearest node_modules/.bin, then from PATH.

Examples:
  # Create a project
  $ ajs project init my-app
  # Add a module from npm
  $ ajs project modules add @antelopejs/api
  # Run the project and reload it on changes
  $ ajs project dev --watch

Run ajs <command> --help for details. Docs: https://antelopejs.com/docs/cli/introduction

Every command and subcommand supports the --help flag; ajs help project is the same as ajs project --help. For a plugin, ajs help <plugin> [command] shows the plugin's own help, like ajs <plugin> [command] --help: ajs help dms prints the help of the DMS plugin. A command page describes what the command does, then lists its arguments, its options, the global options and a few examples:

# Help for project commands
ajs project --help

# Help for a specific subcommand
ajs project dev --help

Options that default to the current directory, such as --project, show (default: current directory) rather than a path. Options that can also be set through an environment variable name it, for example (env: ANTELOPEJS_PROJECT).

Output

Commands that read data (project modules list, project logging show, config show, config get and plugins) write their result, and only their result, on stdout. Context lines, hints, warnings and errors go to stderr, so the result can be piped or redirected safely.

On a terminal, messages, errors with their details and fixes, lists and key/value lines are wrapped to its width between words, each continued line indented under the text it continues. When the output is piped or redirected, lines are written whole.

• On a terminal, lists are aligned tables under a header and settings are aligned key/value lines. A table fits the width of the terminal: its first column is kept whole and the widest other columns are cut with an ellipsis; on a terminal too narrow even for that, each row becomes a block of aligned header and value lines.
• When stdout is piped, tables become one tab-separated line per row, without a header, so they can be processed with cut, awk or grep.
• With -j, --json, stdout holds exactly one JSON document, and the update notice is never shown.

# Names of the configured modules
ajs project modules list | cut -f1

# Version of the dms plugin, if installed
ajs plugins --json | jq -r '.[] | select(.name == "dms") | .version'

Progress and Summaries

Commands that do work (project build, dev, start and project modules add, install, update, remove) report their progress on stderr, one line per task. A task that took a second or more shows its duration.

• On an interactive terminal, running tasks are drawn as a live list, one animated line each. Log lines and module output printed in the meantime appear above the list.
• In CI (CI=true), when stderr is piped, and with --verbose, nothing is animated: each task prints a single line when it finishes.
• With --quiet, tasks print nothing unless they end with a warning or an error.

Log lines (--verbose in particular) are feedback too: during a CLI command such as project build or project modules install they all go to stderr. Once project dev, run or start launches the application, its log lines are its output: on stdout, with errors on stderr.

These commands end with one summary: what was done, what was written and how long it took, followed by the commands that usually come next.

✔ Installed dependencies for module-a 2.3s
✔ Installed dependencies for module-b 2.4s
✔ Loaded 2 modules 2.4s
Built 2 modules → ./.antelope/build/build.json · 2.4s

Next steps
  ajs project start  start the project from this build

When several modules fail to load, each failure is listed once, followed by a single error that carries the fixes.

Errors

When a command fails, ajs prints one error on stderr: what failed, why and the details, then how to fix it. Known low-level failures (a missing path, an unknown npm package, an unreachable registry, a git repository that cannot be cloned) are explained in plain words. When a command run by ajs fails, the error shows the last lines of its output.

✖ Package '@acme/missing' not found on the npm registry
  The registry answered 404: the name is wrong or the package is private.
  Run with --verbose to see the command output.
  → Check the name: npm view @acme/missing

When --verbose would show more (a stack trace, or command output beyond the lines already printed), the error says so. Run the command again with --verbose to see stack traces and the full output of the failed command.

Exit Codes

Every command reports its outcome through its exit code, so scripts and CI jobs can rely on it:

Cancelling ajs project init prints Cancelled and leaves no antelope.config.ts behind, so you can run it again. Stopping ajs project dev or ajs project start with Ctrl+C exits with 130 too, once the project has stopped.

Plugins

Official plugins are separate packages that add command groups to the CLI. The core resolves ajs <plugin> to the plugin executable and forwards the remaining arguments to it.

Resolution Order

The CLI looks for the plugin executable in this order, the way npx resolves a project-local binary:

1. node_modules/.bin/<binary> in the current working directory, then in each parent directory up to the filesystem root (local). On Windows the .cmd, .exe and .bat variants are tried too.
2. The directories of PATH, which is where a global installation lives (global).
3. Nothing found: ajs <plugin> offers to install the plugin globally. The prompt defaults to No. Without an interactive terminal, the command fails and prints the install command instead.

A project that lists the plugin in its dependencies therefore always runs its own version, from the project root or from any subdirectory, and never gets the global install prompt. The version compatibility check reads the package.json of the executable that was actually resolved, so a project-local plugin is checked against its own version rather than the globally installed one.

A command that is neither a core command nor an official plugin runs a third-party ajs-<name> executable when one resolves the same way. The CLI first prints Running third-party plugin ajs-<name> (<path>) on stderr, so a typo never runs an unexpected program silently.

# List official plugins, where they resolve from and their version
ajs plugins

# Run a plugin command (project-local binary first, then PATH,
# then an offer to install the plugin globally when missing)
ajs dms <command>

# Update the CLI and every globally installed official plugin
ajs update

# Update a single plugin
ajs update dms

Plugins are released independently of @antelopejs/core and declare the core versions they support through peerDependencies. When the installed plugin does not support the running CLI, the command stops with an error naming both versions.

Plugins print their output with the @antelopejs/core/cli module, so their messages, errors and exit codes read like those of the core commands.

--no-color, --verbose and --quiet given before the plugin name reach the plugin through its environment, as NO_COLOR=1, ANTELOPEJS_VERBOSE (the channel list, or * for every channel) and ANTELOPEJS_QUIET=1: ajs --no-color dms dev runs ajs-dms dev without colors. Everything after the plugin name, options included, is forwarded to the plugin unchanged.

ajs plugins prints one row per official plugin with its package, version, source (local or global), status and location:

PLUGIN  PACKAGE                   VERSION  SOURCE  STATUS                         LOCATION
dms     @antelopejs/dms-frontend  0.9.0    local   needs @antelopejs/core ^2.0.0  ./node_modules/.bin/ajs-dms
→ Update @antelopejs/dms-frontend in this project's package.json

The status is compatible, needs @antelopejs/core <range> when the plugin does not support the running CLI (running it would fail), unknown when its package.json cannot be read, or not installed. For a plugin that is not installed, a hint on stderr gives the command that installs it. ajs plugins --json prints the same information as a JSON array.

Plugins that resolve from a project node_modules are managed by the project package manager: ajs update leaves them alone and only updates the CLI and the globally installed plugins.

ajs update uses the package manager that installed the CLI globally (npm, pnpm, or Yarn Classic), updates one package at a time, and stops at the first failure. It requires a global installation: when the CLI comes from a project dependency or a source checkout, it refuses to modify a global installation. ajs update <plugin> checks the name first: a name that is not an official plugin fails with a usage error (exit code 2) whatever the installation.

Environment Variables

Update Notice

When a newer version of @antelopejs/core is published, ajs prints one line on stderr after the command output:

ℹ Update available 1.10.3 → 1.12.0  → ajs update

The CLI asks the npm registry at most once a day, in the background, and gives up after one second; the answer is cached in ~/.antelopejs/update-check.json. The check is skipped when stderr is not a terminal, when CI or AJS_NO_UPDATE_CHECK is set, and for --help, --version, --json, --quiet and ajs help.

Configuration Storage

The CLI stores global settings in a JSON file at a platform-specific location:

This file holds values such as the default interface repository URL. You manage it through the ajs config commands rather than editing it by hand. See the Configuration page for details.