Project Commands
Overview
The ajs project command group covers the full project lifecycle. This group handles project creation, development, production builds, module management, and logging configuration.
Project Lifecycle
ajs project init
Create a new AntelopeJS project with an interactive wizard that sets up the configuration file and project structure.
ajs project init <project>
| Argument | Description |
|---|---|
project | Name of the project directory to create |
The wizard walks you through selecting modules, configuring environments, and generating the antelope.config.ts file. Once complete, your project is ready for development with ajs project dev.
Example:
ajs project init my-app
ajs project dev
Start the project in development mode. The core resolves modules, installs dependencies, and launches the runtime.
ajs project dev [options]
| Option | Description |
|---|---|
-p, --project <path> | Path to the project folder |
-e, --env <environment> | Environment name to load |
-w, --watch | Enable file watching and Hot Module Reloading (HMR) |
-c, --concurrency <number> | Number of modules to load in parallel |
--inspect [host:port] | Enable the Node.js debugger |
-i, --interactive | Enable REPL mode for live interaction |
--verbose | Enable verbose logging channels |
Examples:
# Start with HMR
ajs project dev --watch
# Specify project path and environment
ajs project dev -p ./my-app -e staging
# Enable the Node.js debugger
ajs project dev --inspect 0.0.0.0:9229
# Start in interactive REPL mode
ajs project dev -i
ajs project dev --watch during development for automatic HMR when source files change.ajs project run
An alias for ajs project dev. This command accepts all the same options and behaves identically.
ajs project run [options]
ajs project build
Produce build artifacts for production deployment. The command resolves modules, bundles configuration, and writes a manifest to .antelope/build/build.json.
ajs project build [options]
| Option | Description |
|---|---|
-p, --project <path> | Path to the project folder |
-e, --env <environment> | Environment name to build for |
--verbose | Enable verbose logging channels |
Example:
ajs project build -e production
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 pre-built artifacts. This command loads the manifest from .antelope/build/build.json and skips module resolution, making startup faster and deterministic.
ajs project start [options]
| Option | Description |
|---|---|
-p, --project <path> | Path to the project folder |
-e, --env <environment> | Environment name |
-c, --concurrency <number> | Number of modules to load in parallel |
--verbose | Enable verbose logging channels |
Example:
ajs project start -e production
Development-to-Production Workflow
The lifecycle commands form a clear progression from development through deployment:
ajs project dev— Run the project with live module resolution. Add--watchfor HMR during active development.ajs project build— Generate an optimized build artifact (build.json) that locks down module versions and configuration.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.
ajs project modules add <modules...> [options]
| Argument | Description |
|---|---|
modules | One or more module names or paths to add |
| Option | Description |
|---|---|
-m, --mode <mode> | Source type: package (npm), git, local, or dir (local-folder, no compilation). Defaults to package. |
-p, --project <path> | Path to the project folder |
-e, --env <environment> | Environment name |
--ignoreCache | Ignore cached module data and fetch fresh |
Examples:
# Add an npm package (the default mode)
ajs project modules add @antelopejs/api
# Add a local module by path
ajs project modules add ./modules/auth --mode local
# Add multiple npm modules at once
ajs project modules add @antelopejs/api @antelopejs/database
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]
| Argument | Description |
|---|---|
modules | One or more module names to remove |
| Option | Description |
|---|---|
-p, --project <path> | Path to the project folder |
-e, --env <environment> | Environment name |
-f, --force | Force removal without confirmation |
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]
| Option | Description |
|---|---|
-p, --project <path> | Path to the project folder |
-e, --env <environment> | Environment name |
Example:
ajs project modules list
ajs project modules update
Update npm modules to their latest versions. When called without arguments, all npm modules are updated. Pass specific module names to update only those.
ajs project modules update [modules...] [options]
| Argument | Description |
|---|---|
modules | Optional list of module names to update |
| Option | Description |
|---|---|
-p, --project <path> | Path to the project folder |
-e, --env <environment> | Environment name |
--dry-run | Show what would be updated without applying changes |
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
Analyze the project for unresolved interface imports and install the matching modules from the interface repository. This command bridges the gap between declaring interface dependencies in code and having the correct modules available at runtime.
ajs project modules install [options]
| Option | Description |
|---|---|
-p, --project <path> | Path to the project folder |
-e, --env <environment> | Environment name |
--git <repo> | Custom interface repository URL |
Example:
ajs project modules install
install subcommand scans your modules for interface imports that no installed module satisfies. The subcommand then queries the interface repository to find and install compatible modules automatically.Logging Configuration
These subcommands control the project's logging behavior. You can view the current configuration and adjust settings such as log level, format, and module filters.
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]
| Option | Description |
|---|---|
-p, --project <path> | Path to the project folder |
-e, --env <environment> | Environment name |
-j, --json | Output configuration in JSON format |
Example:
ajs project logging show --json
ajs project logging set
Configure logging settings for 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]
| Option | Description |
|---|---|
--enable | Enable logging |
--disable | Disable logging |
--enableModuleTracking | Enable module tracking in log output |
--disableModuleTracking | Disable module tracking in log output |
--includeModule <module> | Add a module to the inclusion filter |
--excludeModule <module> | Add a module to the exclusion filter |
--removeInclude <module> | Remove a module from the inclusion filter |
--removeExclude <module> | Remove a module from the exclusion filter |
--level <level> | Set log level: trace, debug, info, warn, error, default |
--format <format> | Set the log format template |
--dateFormat <format> | Set the date format string |
-i, --interactive | Configure logging interactively |
-p, --project <path> | Path to the project folder |
-e, --env <environment> | Environment name |
Examples:
# Enable logging at debug level
ajs project logging set --enable --level debug
# Only show logs from a specific module
ajs project logging set --includeModule @antelopejs/api
# Customize the log format for the INFO level
ajs project logging set --level info --format "{{chalk.gray}}[{{DATE}}]{{chalk.reset}} {{ARGS}}"
# Use interactive mode to configure all options
ajs project logging set -i
The --level flag selects which level's template the --format string applies to (trace, debug, info, warn, error, or default for the fallback). The template accepts these placeholders:
| Placeholder | Description |
|---|---|
{{DATE}} | Timestamp formatted according to --dateFormat |
{{ARGS}} | The log message content |
{{CHANNEL}} | Channel name |
{{MODULE}} | Originating module ID (when module tracking is on) |
{{chalk.<color>}} | Inline chalk directive (e.g., {{chalk.red}}, {{chalk.bold}}) — stripped when the output is redirected to a non-TTY |
ajs project logging set -i for an interactive guided experience when configuring multiple logging options at once.