Amber CLI

Crystal CI GitHub release Docs

A powerful command-line tool for managing Crystal web applications built with the Amber Framework. This CLI provides generators, database management, development utilities, and more to streamline your Amber development workflow.

📖 Documentation

→ Complete Documentation

The comprehensive documentation includes detailed guides, examples, and API references generated from the codebase.

🚀 Quick Start

Installation

macOS & Linux via Homebrew:

brew tap amberframework/amber_cli
brew install amber_cli

From Source:

git clone https://github.com/amberframework/amber_cli.git
cd amber_cli
shards install
crystal build src/amber_cli.cr -o amber --release
crystal build src/amber_lsp.cr -o amber-lsp --release
sudo mv amber amber-lsp /usr/local/bin/

Windows: Use WSL2 or a virtual machine. Native Windows support is not currently available.

Create Your First App

# Create a new Amber application
amber new my_blog

# Navigate to your app
cd my_blog

# Set up the database
amber database create
amber database migrate

# Start the development server
amber watch

Your application will be available at http://localhost:3000

⚡ Core Commands

| Command | Description | Example | |---------|-------------|---------| | new | Create a new Amber application | amber new my_app -d pg -t slang | | generate | Generate application components | amber generate model User name:String | | database | Database operations and migrations | amber database migrate | | watch | Development server with auto-reload | amber watch | | routes | Display application routes | amber routes --json | | exec | Execute Crystal code in app context | amber exec 'puts User.count' | | encrypt | Manage encrypted environment files | amber encrypt production | | pipelines | Show pipeline configuration | amber pipelines | | setup:lsp | Configure the Amber LSP for Claude Code | amber setup:lsp |

Run amber --help or amber [command] --help for detailed usage information.

🔧 Key Features

Flexible Code Generation

Database Management

Development Tools

Amber LSP — AI-Assisted Development

Extensible Architecture

🏗️ Architecture Highlights

Zero External Dependencies

Clean Command Structure

Smart Template System

🤖 Amber LSP — The Default Development Workflow

Amber ships with a diagnostics-only Language Server that integrates with Claude Code. When you develop with Claude Code, the LSP runs in the background and automatically catches framework convention violations — wrong controller names, missing methods, bad inheritance, file naming issues, and more. Claude sees these diagnostics and self-corrects without you having to notice or intervene.

This is the recommended way to develop with Amber. The LSP turns Claude Code from a general-purpose coding assistant into one that understands Amber's conventions natively.

Quick Setup

# From your Amber project directory:
amber setup:lsp

This creates three files:

| File | Purpose | |------|---------| | .lsp.json | Tells Claude Code where the LSP binary is and what files it handles | | .claude-plugin/plugin.json | Plugin manifest so Claude Code discovers the LSP | | .amber-lsp.yml | Rule configuration — customize severity, disable rules, add custom rules |

Then open Claude Code in your project. The LSP activates automatically.

What It Checks

The LSP ships with 15 built-in rules covering controllers, jobs, channels, pipes, mailers, schemas, routing, file naming, directory structure, and more. Every rule maps to an Amber convention — if Claude generates a controller that doesn't end with Controller, or a job without a perform method, the LSP flags it immediately.

Custom Rules

You can define project-specific rules in .amber-lsp.yml using regex patterns. No recompilation needed:

custom_rules:
  - id: "project/no-puts"
    description: "Do not use puts in production code"
    severity: warning
    applies_to: ["src/**"]
    pattern: "^\\s*puts\\b"
    message: "Avoid 'puts' in production code. Use Log.info instead."

Building the LSP Binary

If amber-lsp is not on your PATH, the setup:lsp command will offer to build it:

cd ~/open_source_coding_projects/amber_cli
crystal build src/amber_lsp.cr -o bin/amber-lsp --release

For full documentation on all 15 rules, configuration options, and custom rule syntax, see the LSP Setup Guide.

📚 Examples

Generate a Blog Post Resource

# Create model, controller, views, and migration
amber generate scaffold Post title:String content:Text published:Bool

# Or generate individually
amber generate model Post title:String content:Text
amber generate controller Posts
amber generate migration add_published_to_posts published:Bool

Custom Development Workflow

# Watch with custom build commands
amber watch --build "crystal build src/app.cr --release" --run "./app"

# Execute code in application context
amber exec 'Post.where(published: true).count'

# Encrypt production environment
amber encrypt production --editor vim

Database Operations

# Create and set up database
amber database create
amber database migrate
amber database seed

# Check migration status
amber database status

# Rollback last migration
amber database rollback

🔍 Configuration

Amber CLI uses several configuration files:

Example .amber.yml:

database: pg
language: slang
model: granite
watch:
  run:
    build_commands:
      - "crystal build ./src/my_app.cr -o bin/my_app"
    run_commands:
      - "bin/my_app"
    include:
      - "./config/**/*.cr"
      - "./src/**/*.cr"

🤝 Contributing

We welcome contributions! Please read our Contributing Guide for details.

  1. Fork the repository
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Write tests for your changes
  4. Ensure all tests pass (crystal spec)
  5. Follow Crystal's code formatting (crystal tool format)
  6. Commit your changes (git commit -am 'Add some feature')
  7. Push to the branch (git push origin my-new-feature)
  8. Create a Pull Request

📋 Requirements

🐛 Troubleshooting

Common issues and solutions:

Database connection errors:

# Verify database is running and check config
amber database status

Generation failures:

# Check template availability
amber generate --list

Watch mode not working:

# Show current configuration
amber watch --info

For more detailed troubleshooting, see the full documentation.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🌟 Acknowledgments

→ View Complete Documentation