Project Commands

Overview

The ajs project command group covers the full project lifecycle: project creation, development, production builds, module management, and logging configuration.

Every command of the group accepts the global options (--verbose, --quiet, --no-color, --help). The commands that read a project accept -p, --project <path>, which defaults to the current directory, and -e, --env <environment>, which selects an entry of environments in antelope.config.ts instead of the base configuration. When antelope.config.ts declares no environments, --env accepts any name and the base configuration is used; otherwise an undeclared name is a usage error (exit code 2). Their defaults can also be set with ANTELOPEJS_PROJECT and ANTELOPEJS_LAUNCH_ENV.

Project Lifecycle

ajs project init

Create a project folder with an antelope.config.ts file and its first module. The first module is either an existing module, imported from npm, git or a local path, or a new module created from a template of the interface repository.

ajs project init <project> [options]

The command asks for the project name, then whether to import an existing module. An imported module comes from package (an npm package name), git (a repository URL) or local (a path). Otherwise the command creates the first module from a template and asks the same questions as ajs module init: template, interfaces, package manager and git repository. Every question is answered before anything is written: cancelling with Ctrl+C writes nothing and exits with code 130.

Each question can be answered with its flag, so the command runs in scripts and CI. When standard input is not a terminal, or CI is set, the command never prompts: the project is named after its directory unless --name is given, and is created from a template. The project path and the interface repository are checked first, so an existing project or an unreachable repository is reported as such; then a question that no flag answers makes the command exit with code 2 before anything is written, and the error lists the flags to pass. --yes answers the remaining questions with their defaults: the directory name, the first template, no interface, npm and a git repository.

Examples:

# Answer the questions interactively
ajs project init my-app

# Accept every default
ajs project init my-app --yes

# Answer every question with a flag, for scripts and CI
ajs project init my-app --template "Blank Typescript" --pm pnpm --no-git-init

The command ends with a summary and the commands that usually come next:

Created project my-app → ./my-app

Next steps
  cd ./my-app
  ajs project modules install  add modules for the interfaces no module implements
  ajs project dev --watch      run the project and reload it on changes

ajs project dev

Run the project in development mode: download and install its modules, then load and connect them.

ajs project dev [options]

Add the global --verbose option to see TRACE logs, for example ajs project dev --verbose=loader.

Press Ctrl+C to stop the project, at any time, including while its modules are still loading or starting. A launch still in progress stops there: the module version check no longer waits for the npm registry, and the modules not loaded, constructed or started yet are left alone. ajs stops and destroys the modules, terminates the processes they started and left running (a sidecar or a dev server, for example), prints Stopped the project and exits with code 130. SIGTERM stops the project the same way and exits with code 0. The modules get 10 seconds to stop: past that, the shutdown reports that it timed out, still terminates the leftover processes, and exits. Press Ctrl+C again to exit at once without waiting for the modules; the leftover processes are killed all the same.

Examples:

# Run the project and reload it on changes
ajs project dev --watch

# Run another project with its staging environment
ajs project dev -p ./my-app -e staging

# Enable the Node.js inspector
ajs project dev --inspect 0.0.0.0:9229

# Open a REPL with the project loaded
ajs project dev -i

ajs project run

The former name of ajs project dev, kept for compatibility. It accepts the same options and behaves identically; use ajs project dev in new scripts.

ajs project run [options]

ajs project build

Build the project for production: download and install its modules, check that every module loads, and write the build artifact .antelope/build/build.json.

ajs project build [options]

Example:

ajs project build -e production

✔ Installed dependencies for my-module
✔ Loaded 1 module
Built 1 module → ./.antelope/build/build.json · 824ms

Next steps
  ajs project start  start the project from this build

The generated build.json contains module manifests and a configuration hash. The ajs project start command reads this file to launch the application without repeating the resolution step.

ajs project start

Start the project from the build artifact .antelope/build/build.json. The command skips module download and resolution, which makes startup faster and deterministic.

ajs project start [options]

Example:

ajs project start -e production

ajs project start dispatches directly to the production runtime without loading the developer CLI, scaffolding commands, or performing the CLI update check against the npm registry. Use this command in production containers and process managers after ajs project build.

SIGTERM and Ctrl+C stop the project like they stop ajs project dev: the exit code is 0 after SIGTERM and 130 after Ctrl+C.

Build once, start with the runtime configuration

By default, ajs project start runs every module with the configuration ajs project build resolved and stored in build.json. A container image built that way carries the configuration of the build environment, secrets included.

Pass --refresh-config to build the image once, without secrets, and start it with the configuration of the environment it runs in:

# Image build: download, install and validate modules
ajs project build -e production

# Container start: resolve antelope.config.ts against this environment
ajs project start -e production --refresh-config

At start, the command resolves antelope.config.ts for the --env environment the same way ajs project build does, including environments entries, antelope.<module>.json files, and envOverrides read from the process environment. When the configuration loads the same modules from the same sources as the build, each module starts with its refreshed config, importOverrides, and disabledExports, along with the refreshed logging settings. Module files, manifests, and the cache folder stay those of the build. The refreshed artifact only lives in memory: build.json is never rewritten, so the secrets never reach the disk.

Two module sets match when they declare the same module ids with the same source, relative local paths being resolved against the project folder. Otherwise the command starts nothing and exits with code 3, so a start script can fall back to a full build:

status=0
ajs project start -e production --refresh-config || status=$?
if [ "$status" -eq 3 ]; then
  ajs project build -e production
  exec ajs project start -e production
fi
exit "$status"

Invalid arguments exit with code 2 and any other failure with code 1. Modules loaded from a local-folder source cannot be traced back to their source in the build, so a project that uses one always needs a full build.

Programmatic callers pass { refreshConfig: true } to launchFromBuild(), which rejects with a BuildModuleSetChangedError when the module set differs.

Development-to-Production Workflow

The lifecycle commands form a clear progression from development through deployment:

1. ajs project dev — Run the project with live module resolution. Add --watch for HMR during active development.
2. ajs project build — Generate the build artifact (build.json) that locks down module versions and configuration.
3. ajs project start — Launch from the build artifact in production. Skips resolution for faster, reproducible startup.

# Development
ajs project dev --watch

# Build for production
ajs project build -e production

# Start in production
ajs project start -e production

Module Management

These subcommands manage the modules installed in a project. You can add, remove, list, update, and auto-install modules from the command line.

ajs project modules add

Add one or more modules to the project configuration and download them.

ajs project modules add <modules...> [options]

The last column is the source ajs project modules list shows for the module.

In package mode, a module can be given as <name> or <name>@<spec>, where the spec is an exact version, a semver range, or a dist-tag. Without a spec, the latest published version is written as a floating caret range (^1.3.2), so the module follows new minor and patch releases automatically. Pass an exact version to pin the module instead. Invalid specs are rejected immediately, and a module whose download fails is not added to the configuration.

Examples:

# Add the latest version of an npm package (writes a ^ range)
ajs project modules add @antelopejs/api

# Pin an exact version
ajs project modules add @antelopejs/[email protected]

# Use a semver range or a dist-tag
ajs project modules add @antelopejs/api@~1.3.0
ajs project modules add @antelopejs/api@next

# Add a module from a local folder
ajs project modules add ./modules/auth --mode local

# Add several npm modules at once
ajs project modules add @antelopejs/api @antelopejs/mongodb

✔ Added @antelopejs/api 1.3.2 5.0s
1 module added to antelope.config.ts · 5.2s

Next steps
  ajs project modules install  resolve the interfaces they need

ajs project modules remove

Remove one or more modules from the project. Also available under the alias rm.

ajs project modules remove <modules...> [options]
ajs project modules rm <modules...> [options]

Without --force, nothing is removed when one of the names is not in the configuration.

Example:

ajs project modules remove @antelopejs/api --force

ajs project modules list

List all modules installed in the project. Also available under the alias ls.

ajs project modules list [options]
ajs project modules ls [options]

The modules are printed as a table with their name, source (npm, git, local or folder) and reference (version, repository or path). On a narrow terminal, long references are cut with an ellipsis; when the terminal is too narrow even for that, each module is printed as a block of NAME, SOURCE and REFERENCE lines. When stdout is piped, each module is one tab-separated line without a header. With --json, the command prints an array of { "name", "source" } objects, where source is the module source as configured.

Examples:

ajs project modules list

# Print the module names only
ajs project modules list | cut -f1

ℹ 3 modules in acme-shop (default)
NAME                  SOURCE  REFERENCE
@antelopejs/api       npm     1.0.0
@antelopejs/auth-jwt  npm     ^1.0.0
billing               local   modules/billing

ajs project modules update

Check npm for newer versions of the npm modules of the project and write them to the project configuration. When called without arguments, all npm modules are updated. Pass specific module names to update only those. Modules from git or local folders are left as they are.

ajs project modules update [modules...] [options]

Examples:

# Update all npm modules
ajs project modules update

# Preview updates without applying
ajs project modules update --dry-run

# Update a specific module
ajs project modules update @antelopejs/api

ajs project modules install

Find the interfaces that the modules of the project import but no module implements, and add a module that implements each of them, taken from the interface repository. Despite its name, the command does not install npm dependencies: it completes the module set of the project.

ajs project modules install [options]

Examples:

ajs project modules install

# In CI: never prompt, take the first implementation when there is a choice
ajs project modules install --yes

Logging Configuration

These subcommands show and change the logging block of antelope.config.ts. The runtime applies these settings when the project runs with ajs project dev, build or start: logging on or off, module tracking and its filters, the date format and the templates of each level.

ajs project logging show

Display the current logging configuration. Also available under the alias ls.

ajs project logging show [options]
ajs project logging ls [options]

The command prints a summary of the settings as key/value lines. The level templates are only printed with --json, which outputs the full logging configuration merged with the defaults.

Example:

ajs project logging show

ℹ Logging configuration of acme-shop (default)
Enabled          yes
Module tracking  only billing
Date format      yyyy-MM-dd HH:mm:ss
Level formats    custom for INFO, see --json for the templates

ajs project logging set

Change the logging settings of the project. You can toggle logging, control module tracking, filter which modules produce log output, and customize the log format.

ajs project logging set [options]

The camelCase spellings of earlier versions (--enableModuleTracking, --disableModuleTracking, --includeModule, --excludeModule, --removeInclude, --removeExclude and --dateFormat) still work until the next minor version. They are hidden from the help and print a deprecation warning that names the new spelling.

The include and exclude lists filter log lines by module, so they only apply while module tracking is on. With a non-empty include list, only the listed modules log.

Examples:

# Enable logging
ajs project logging set --enable

# Only show the logs of one module
ajs project logging set --enable-module-tracking --include-module @antelopejs/api

# Use a custom template for DEBUG lines
ajs project logging set --level debug --format "[{{DATE}}] {{ARGS}}"

# Customize the INFO lines, with styles
ajs project logging set --level info --format "{{chalk.gray}}[{{DATE}}]{{chalk.reset}} {{ARGS}}"

# Answer the questions interactively
ajs project logging set -i

✔ Module tracking enabled
✔ Added @antelopejs/api to the include list
Saved the logging configuration of my-app

Next steps
  ajs project logging show  view the current settings

Only the settings that actually change are written to antelope.config.ts, in the logging block of the selected environment. When every setting is already in place, the command says so and leaves the file untouched. Without any setting, or with --interactive, the command asks its questions interactively; when standard input is not a terminal, or CI is set, it exits with code 2 instead and names the setting flags to pass. Cancelling the questions with Ctrl+C writes nothing and exits with code 130.

The --level flag selects which level's template the --format string applies to (trace, debug, info, warn, error, or default for the levels without a template of their own). The two flags go together: one without the other exits with code 2. --level does not set a minimum log level; to show DEBUG and TRACE lines, run ajs project dev, build or start with --verbose.

The runtime renders every log line of a level with its saved template, which replaces the whole line: the module prefix and the right-aligned date of the built-in format are not added, use {{MODULE}} and {{DATE}} instead. Levels without a saved template keep the built-in format. The template accepts these placeholders: