Download Almadar CLI
The Almadar CLI (almadar) is the command-line tool for validating, compiling, and working with Almadar schemas.
Quick Install
npm (Recommended)
npm install -g @almadar/cli
Homebrew (macOS/Linux)
brew install almadar/tap/almadar
Cargo (Rust developers)
cargo install almadar-cli
Platform-Specific Downloads
Linux
| Architecture | Format | Download |
|---|---|---|
| x86_64 | tar.gz | almadar-linux-x86_64.tar.gz |
| x86_64 | deb | almadar_x86_64.deb |
| x86_64 | rpm | almadar-x86_64.rpm |
| ARM64 | tar.gz | almadar-linux-aarch64.tar.gz |
Installation (tar.gz):
tar -xzf almadar-linux-x86_64.tar.gz
sudo mv almadar /usr/local/bin/
Installation (deb):
sudo dpkg -i almadar_x86_64.deb
macOS
| Architecture | Format | Download |
|---|---|---|
| Intel (x86_64) | tar.gz | almadar-macos-x86_64.tar.gz |
| Apple Silicon (ARM64) | tar.gz | almadar-macos-aarch64.tar.gz |
| Universal | pkg | almadar-macos.pkg |
Installation (tar.gz):
tar -xzf almadar-macos-aarch64.tar.gz
sudo mv almadar /usr/local/bin/
Windows
| Architecture | Format | Download |
|---|---|---|
| x86_64 | zip | almadar-windows-x86_64.zip |
| x86_64 | msi | almadar-windows-x86_64.msi |
Installation (winget):
winget install Almadar.CLI
Installation (zip):
- Extract
almadar-windows-x86_64.zip - Add the extracted folder to your PATH
- Restart your terminal
Verify Installation
almadar --version
# Almadar CLI v1.0.0
almadar --help
# Almadar - The Physics of Software
#
# USAGE:
# almadar <COMMAND>
#
# COMMANDS:
# validate Validate an Almadar schema
# compile Compile schema to target shell
# format Format an Almadar schema
# dev Start development server
# test Run state machine tests
# new Create a new project
# help Print this message
Basic Usage
Validate a Schema
almadar validate my-app.orb
# ✓ Schema is valid
# ✓ 3 orbitals, 5 traits, 8 entities
Compile to TypeScript
almadar compile my-app.orb --shell typescript --output ./generated
# ✓ Generated 24 files
# ✓ Output: ./generated
Start Development Server
almadar dev my-app.orb
# Starting Almadar dev server...
# ✓ Schema loaded: my-app.orb
# ✓ Server: http://localhost:3000
# ✓ Client: http://localhost:5173
#
# Watching for changes...
Run Tests
almadar test my-app.orb
# Running state machine tests...
# ✓ TaskLifecycle: 12 transitions tested
# ✓ UserAuth: 8 transitions tested
# ✓ All guards evaluated
#
# Tests: 20 passed, 0 failed
Create New Project
almadar new my-app
# ✓ Created my-app/
# ✓ Created my-app/schema.orb
# ✓ Created my-app/almadar.config.json
#
# Get started:
# cd my-app
# almadar dev
Configuration
Create an almadar.config.json in your project root:
{
"$schema": "https://almadar.io/schemas/config.json",
"schema": "./schema/my-app.orb",
"output": "./src/generated",
"shell": "typescript",
"locale": "en",
"features": {
"hotReload": true,
"generateTypes": true,
"generateDocs": true
}
}
Then simply run:
almadar compile
# Uses settings from almadar.config.json
Locale Support
Almadar supports multiple languages for error messages and operator aliases:
# English (default)
almadar validate schema.orb --locale en
# Arabic
almadar validate schema.orb --locale ar
# ✓ المخطط صالح
# ✓ ٣ مدارات، ٥ سمات، ٨ كيانات
Next Steps
- Your First Schema - Build something!
- CLI Reference - Complete command reference
- Editor Extensions - VSCode and Zed support
Troubleshooting
"Command not found"
Ensure the binary is in your PATH:
# Check where almadar is installed
which almadar
# Add to PATH if needed (add to ~/.bashrc or ~/.zshrc)
export PATH="$PATH:/path/to/almadar"
Permission Denied (Linux/macOS)
chmod +x /usr/local/bin/almadar
Windows Defender Warning
The almadar.exe binary is signed but may trigger Windows Defender on first run. Click "More info" → "Run anyway" or add an exception.