AxilJS CLI Troubleshooting

This guide covers common issues when installing, updating, and using the AxilJS CLI.

The recommended troubleshooting process is to first verify the installed CLI version, run axil doctor, verify project dependencies, and then retry the command that produced the error.

axil Command Not Found#

If your terminal reports that axil is not recognized or the command cannot be found, first install the AxilJS CLI globally:

Then verify the installation:

If the command is still unavailable, the npm global binary directory may not be included in your system PATH.

Restart your terminal after installation and try again.

On Windows, you can close and reopen Command Prompt, PowerShell, or Windows Terminal so the updated environment is loaded.

Check the Installed CLI Version#

Display the currently installed AxilJS CLI version:

If you need to update the CLI to the latest published version:

Then verify the installed version:

Checking the version is an important first step when troubleshooting differences between environments or unexpected CLI behavior.

Reinstall the CLI#

If the global CLI installation appears corrupted or behaves unexpectedly, uninstall it:

Install the CLI again:

Verify the installation:

This provides a clean global installation of the AxilJS CLI.

Project Dependencies#

If an AxilJS project fails to start, make sure its project dependencies are installed.

Run:

Then start the development server:

Run these commands from the root directory of the AxilJS project.

Custom Entry Point Problems#

If the CLI cannot find or start the expected application entry point, provide the entry point explicitly:

Make sure that:

• The specified file exists.
• The file is a valid TypeScript entry module.
• You are running the command from the project root.

A custom entry point is useful when the project uses a non-standard application structure.

Development Server Issues#

Start the development server with:

If the project uses a custom entry point:

If the application still fails to start, run the diagnostic command:

The diagnostic command can help identify project, environment, dependency, or CLI-related problems.

Build Issues#

If the production build fails, first ensure that project dependencies are installed:

Then run:

Review the compiler output for TypeScript or application-level errors.

The AxilJS CLI build command does not replace fixing errors in the application source itself. If the compiler reports source-level errors, resolve those errors and run the build again.

Test Issues#

Run the complete test suite:

To target a particular test pattern:

For example:

Review the test runner output for the underlying test or configuration error.

If the issue is not related to a specific test pattern, run the complete test suite to determine whether the problem affects the project generally.

Deployment Issues#

Generate deployment artifacts with:

The command generates Docker and Kubernetes configuration files.

If deployment generation fails, run:

Then verify that the project is correctly installed and configured.

Review generated deployment files before using them in a production environment.

Decorator CLI Issues#

If the AxilJS decorator catalog does not behave as expected, first verify the installed CLI version:

Inspect the available decorator categories:

List the available decorators:

Inspect a specific decorator:

Search the catalog:

If you recently updated the decorator catalog, make sure you are using the latest published CLI version:

Then verify:

This is particularly important when the locally installed CLI contains an older version of the decorator catalog.

Decorator Check Errors#

Use the check command to inspect decorator composition in a source file:

Make sure the file path is correct and that the source file contains the decorators you expect the CLI to analyze.

You can also inspect the decorator metadata graph:

The graph can help inspect relationships between semantic decorators and their associated metadata.

Package Installation Issues#

If an AxilJS package cannot be installed through the CLI:

Try installing the package directly with npm:

For example:

If the package is already installed, inspect the project's dependency tree:

This can help determine whether the expected package version is installed in the current project.

Diagnose the Environment#

The recommended first diagnostic command is:

Run it from the root directory of your AxilJS project:

Use doctor when investigating project configuration, environment, dependency, or CLI-related issues.

Get CLI Help#

Display the complete CLI command reference:

For a specific command:

Command-specific help can reveal available options and expected command syntax.

Windows Troubleshooting#

On Windows, AxilJS CLI commands can be executed from Command Prompt, PowerShell, or Windows Terminal.

For example:

If axil is not recognized immediately after installation, close and reopen the terminal so that the updated environment and PATH configuration are loaded.

If the command remains unavailable after restarting the terminal, verify the global npm installation and the npm global binary directory configuration.

Diagnostic Workflow#

When troubleshooting an AxilJS CLI issue, start with the installed CLI version:

Then diagnose the project environment:

Verify project dependencies:

Retry the command that produced the error:

For production build problems:

For decorator tooling problems:

The troubleshooting sequence can be summarized as:

Check CLI Version
       │
       ▼
  axil doctor
       │
       ▼
 npm install
       │
       ▼
Retry Failed Command
       │
   ┌───┼────────────┐
   ▼   ▼            ▼
  run build      decorator

This workflow helps separate global CLI installation problems from project dependency, configuration, development server, build, deployment, and decorator-catalog issues.