{"title":"Installation","description":"Install Amber CLI 2.0.6 on supported macOS, x86-64 Linux, and ARM64 Linux systems","section":"getting-started","version":"v2","path":"getting-started/installation","canonical_url":"https://amberframework.org/docs/v2/getting-started/installation","markdown_url":"https://amberframework.org/docs/v2/getting-started/installation.md","inherited":false,"content_markdown":"# Install Amber V2 Beta\n\nThe supported onboarding path uses the standalone Amber CLI. The framework is\nan exact shard dependency generated into each application.\n\n## Supported systems\n\n- Apple Silicon macOS — release-gated; Homebrew and `darwin-arm64` archive\n- x86-64 Linux — release-gated; Homebrew and `linux-x86_64` archive\n- ARM64 Linux — release-gated; `linux-arm64` archive\n- Windows x86-64 — generated database-backed app compile-verified in CI; no CLI\n  release archive yet\n\nIntel macOS is not currently verified. Windows is not a release gate until it\nhas a supported installation artifact, but its CI job installs SQLite, builds\nthe CLI, generates the web app, applies its development and test migrations,\nruns the generated specs, and compiles the application. Follow [Beta Support](../beta-support/)\nrather than treating a successful Crystal installation as the complete support\nclaim.\n\n## Prerequisites\n\nInstall Crystal 1.20 or newer, but earlier than 2.0, using the\n[official Crystal instructions](https://crystal-lang.org/install/). You also\nneed Git, `shards`, and SQLite development headers because the default web app\ncompiles the SQLite driver.\n\nFor a new application, use the latest stable Crystal release that satisfies\nthat range.\n\nOn Debian or Ubuntu Linux:\n\n```bash\nsudo apt-get update\nsudo apt-get install -y libsqlite3-dev\n```\n\nThen verify the toolchain:\n\n```bash\ncrystal --version\nshards --version\ngit --version\n```\n\nSQLite needs no running database server. Choose PostgreSQL or MySQL only when\nthe application needs one of those servers.\n\n## Homebrew on macOS or Linux\n\nThe tap and formula use an underscore. Install the official formula with its\nfully qualified name, then verify the `amber` executable:\n\n```bash\nbrew install amberframework/amber_cli/amber_cli\namber --version\n```\n\nThe formula is `amber_cli`; the installed executable is `amber`. Expect Amber\nCLI `2.0.6` or newer.\n\n## Direct archive\n\nChoose `darwin-arm64`, `linux-x86_64`, or `linux-arm64` for the current host.\n\n```bash\nversion=v2.0.6\nplatform=darwin-arm64\nasset=\"amber_cli-${platform}.tar.gz\"\n\ncurl -fLO \"https://github.com/amberframework/amber_cli/releases/download/${version}/${asset}\"\ncurl -fLO \"https://github.com/amberframework/amber_cli/releases/download/${version}/${asset}.sha256\"\nshasum -a 256 -c \"${asset}.sha256\"\ntar -xzf \"${asset}\"\ninstall -m 0755 amber amber-lsp /usr/local/bin/\namber --version\n```\n\nOn Linux, set `platform` to the matching value and use `sha256sum -c`. Prefix\nonly the `install` command with `sudo` when `/usr/local/bin` is not writable.\nNever run a differently named architecture archive through emulation and call\nthat native support.\n\n## Verify a database-backed application\n\n**Run from: a parent directory where `amber_beta_smoke/` can be created.**\n\n```bash\namber new amber_beta_smoke --type web\ncd amber_beta_smoke\namber assets check\namber generate scaffold Pet name:string:required species:string:required adopted:bool\namber database migrate\nAMBER_ENV=test amber database migrate\ncrystal spec\ncrystal build src/amber_beta_smoke.cr -o bin/amber_beta_smoke\namber watch\n```\n\nOpen <http://127.0.0.1:3000/>, then create a record at\n<http://127.0.0.1:3000/pets/new>. The generated `shard.yml` pins Amber\n`2.0.0-beta.5`, includes Grant and only the selected database driver, and does\nnot use a personal Amber fork or a moving framework branch.\n\nFrom another terminal:\n\n```bash\ncurl --fail http://127.0.0.1:3000/\ncurl --fail http://127.0.0.1:3000/pets/new\n```\n\nView the homepage source and follow its fingerprinted `/assets/...` stylesheet\nURL. Confirm the stylesheet and JavaScript module tags include\n`integrity=\"sha256-...\"`; a raw `/css/app.css` request is not the V2 asset\ncontract.\n\n## Manual framework dependency\n\nFor an existing Crystal application that only needs the runtime upgrade:\n\n```yaml\ndependencies:\n  amber:\n    github: amberframework/amber\n    version: 2.0.0-beta.5\n\ncrystal: \">= 1.20.0, < 2.0\"\n```\n\nDo not replace an existing application's working persistence stack merely to\nupgrade the framework. Read the [V1-to-V2 migration guide](../migration-guide/)\nand keep the first upgrade bounded.\n\n## Update or remove\n\n```bash\nbrew update\nbrew upgrade amberframework/amber_cli/amber_cli\n# or\nbrew uninstall amberframework/amber_cli/amber_cli\nbrew untap amberframework/amber_cli\n```\n\n## Troubleshooting\n\nIf the wrong executable runs, inspect every match:\n\n```bash\ntype -a amber\namber --version\n```\n\nRemove or rename an old Amber V1 executable, or put Homebrew earlier in `PATH`.\nOn macOS, the beta binary must not require `openssl@1.1`; include\n`otool -L \"$(command -v amber)\"` in an install issue.\n\nFor generated-app failures, include the operating system and architecture,\n`crystal --version`, `amber --version`, the exact command, and complete output.\nFramework behavior belongs in the Amber issue tracker; CLI, generator,\nmigration-command, and install behavior belongs in Amber CLI."}