Installation

This guide will help you install Azu CLI on your development machine. Azu CLI is distributed as a single binary and works on macOS, Linux, and Windows.

Prerequisites

Before installing Azu CLI, ensure you have the following prerequisites:

Crystal Language

Azu CLI requires Crystal 1.6.0 or higher.

macOS (using Homebrew):

brew install crystal

Ubuntu/Debian:

curl -fsSL https://packagecloud.io/84codes/crystal/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/84codes-crystal.gpg
echo "deb [signed-by=/usr/share/keyrings/84codes-crystal.gpg] https://packagecloud.io/84codes/crystal/ubuntu/ $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/84codes-crystal.list
sudo apt update
sudo apt install crystal

Arch Linux:

sudo pacman -S crystal

From Source:

git clone https://github.com/crystal-lang/crystal.git
cd crystal
make clean crystal

Database (Optional)

Azu applications typically use a database. Install one of the supported databases:

PostgreSQL (Recommended):

# macOS
brew install postgresql

# Ubuntu/Debian
sudo apt install postgresql postgresql-contrib

# Arch Linux
sudo pacman -S postgresql

MySQL:

# macOS
brew install mysql

# Ubuntu/Debian
sudo apt install mysql-server

# Arch Linux
sudo pacman -S mysql

SQLite:

# Usually comes pre-installed on most systems
# macOS
brew install sqlite

# Ubuntu/Debian
sudo apt install sqlite3

# Arch Linux
sudo pacman -S sqlite

Installation Methods

Method 1: From Source (Recommended)

This is the most reliable method and ensures you get the latest version.

1. Clone the repository:

   git clone https://github.com/azutoolkit/azu_cli.git
   cd azu_cli

2. Install dependencies:

   shards install

3. Build and install:

   make install

   This will:

   • Compile the binary in release mode

   • Install it to /usr/local/bin/azu (may require sudo)

   • Make it available system-wide

4. Verify installation:

   azu version

Method 2: Using Make (Alternative)

If you prefer to build manually:

1. Clone and build:

   git clone https://github.com/azutoolkit/azu_cli.git
   cd azu_cli
   make build

2. Install manually:

   sudo make install

Method 3: Symlink Installation (Development)

For development work where you want changes to be reflected immediately:

1. Clone and build:

   git clone https://github.com/azutoolkit/azu_cli.git
   cd azu_cli
   make build

2. Create symlink:

   sudo make link
   # Or force overwrite existing symlink
   sudo make force_link

This creates a symlink from the built binary to /usr/local/bin/azu, so any changes you make to the source will be reflected immediately after rebuilding.

Method 4: Development Installation

For development or if you want to modify Azu CLI:

1. Clone the repository:

   git clone https://github.com/azutoolkit/azu_cli.git
   cd azu_cli

2. Install dependencies:

   shards install

3. Build in development mode:

   crystal build src/azu_cli.cr -o bin/azu

4. Add to PATH (optional):

   export PATH="$PWD/bin:$PATH"
   # Add to your shell profile for persistence
   echo 'export PATH="$PWD/bin:$PATH"' >> ~/.bashrc  # or ~/.zshrc

Post-Installation Setup

1. Verify Installation

azu version
# Should output: Azu CLI v0.0.1+13

azu help
# Should display the help menu

2. Configure Global Settings (Optional)

Create a global configuration file:

mkdir -p ~/.config/azu
cat > ~/.config/azu/config.yml << EOF
# Global Azu CLI configuration
default_database: postgres
default_template: web
editor: code  # or vim, nano, etc.
git_auto_init: true
EOF

3. Set Up Database

If you're planning to use databases, ensure your database server is running:

PostgreSQL:

# macOS (Homebrew)
brew services start postgresql

# Linux (systemd)
sudo systemctl start postgresql
sudo systemctl enable postgresql

# Create a user (optional)
createuser -s $USER

MySQL:

# macOS (Homebrew)
brew services start mysql

# Linux (systemd)
sudo systemctl start mysql
sudo systemctl enable mysql

Troubleshooting

Common Issues

1. "azu: command not found"

Solution 1: Check if the binary is in your PATH:

which azu
echo $PATH

Solution 2: Reinstall with proper permissions:

sudo make install

Solution 3: Add to PATH manually:

export PATH="/usr/local/bin:$PATH"

2. Permission Denied During Installation

# Use sudo for system-wide installation
sudo make install

# Or install to user directory
make install PREFIX=$HOME/.local
export PATH="$HOME/.local/bin:$PATH"

3. Crystal Not Found

Ensure Crystal is properly installed and in your PATH:

crystal version
# Should output Crystal version information

4. Compilation Errors

Update your Crystal installation:

# macOS
brew upgrade crystal

# Linux - follow Crystal installation guide for your distribution

Clear shards cache and reinstall:

rm -rf lib/ shard.lock
shards install

5. Database Connection Issues

Ensure your database service is running:

# PostgreSQL
sudo systemctl status postgresql

# MySQL
sudo systemctl status mysql

# Or check processes
ps aux | grep postgres
ps aux | grep mysql

Getting Help

If you encounter issues during installation:

1. Check the logs during compilation for specific errors

2. Verify prerequisites are properly installed

3. Update Crystal to the latest version

4. Clear build cache: make clean && make build

5. Create an issue on GitHub with:

   • Your operating system and version

   • Crystal version (crystal version)

   • Full error output

   • Installation method used

Available Makefile Targets

The Azu CLI Makefile provides several useful targets:

Target	Description
make or make all	Build and create symlink (default)
make build	Build the binary only
make shard	Install dependencies and build
make install	Build and install binary to system
make link	Create symlink to built binary
make force_link	Force create symlink (overwrites existing)
make run	Run the built binary
make clean	Remove built binary
make distclean	Remove binary and all build artifacts

Examples

# Build only
make build

# Install system-wide
sudo make install

# Create development symlink
sudo make link

# Run without installing
make run

# Clean up
make clean

Updating Azu CLI

To update to the latest version:

cd /path/to/azu_cli
git pull origin master
shards install
make clean
make install

Uninstalling

To remove Azu CLI:

If installed with make install

sudo rm /usr/local/bin/azu
rm -rf ~/.config/azu  # Remove configuration (optional)

If installed with make link

sudo rm /usr/local/bin/azu  # Remove symlink
# The source binary in bin/azu will remain

Complete cleanup

# Remove binary and all build artifacts
make distclean

# Remove configuration
rm -rf ~/.config/azu

---

Next Steps:

• Quick Start Guide - Create your first Azu application

• Project Structure - Understand Azu project organization

• Command Reference - Learn all available commands