Installation

Before creating your first Maat application, install the Dart SDK and Ptah, Maat’s project installer.

Requirements

Maat requires Dart 3.12.0 or later. The generated application does not need Node.js, reflection, or code generation.

Confirm your Dart installation:

dart --version

Install Ptah

Install the maat command globally from pub.dev:

dart pub global activate ptah

Your pub cache’s bin directory must be on PATH. If the command is not found after installation, follow Dart’s printed instructions to add that directory, then open a new terminal.

Create an Application

Create a project and enter its directory:

maat new blog
cd blog

Ptah copies the application skeleton, creates .env from .env.example, runs dart pub get, and generates APP_KEY.

The project name must be a valid Dart package name: start with a lowercase letter and use only lowercase letters, digits, and underscores.

Installer Options

Option	Purpose
--api	Create an API-only application without resources/ or public/.
--force	Write into a non-empty directory and overwrite matching files.
--maat-path=<path>	Use a local Maat checkout instead of published packages.
--skip-install	Skip dart pub get and application-key generation.

Use --force carefully: it overwrites matching files, although it does not delete unrelated files in the target directory.

Run the Development Server

Start the application:

maat serve

The server listens on http://127.0.0.1:8000 and watches lib, config, routes, bootstrap, and .env. When a watched file changes, Maat restarts the process.

Option	Default	Purpose
--host	127.0.0.1	Address to bind.
--port	8000	Port to bind.
--no-watch	—	Run once without the file watcher.

For a server-rendered application, compile Tailwind in a second terminal:

maat tailwind --watch

The API-only preset does not include frontend files. See Frontend for the complete Node-free asset workflow.

Verify the Installation

Request the health route generated with every application:

curl http://127.0.0.1:8000/api/health

You should receive:

{"status":"ok"}

The skeleton also includes a feature test for this route:

dart test

Next Step

Continue with Build Your First Maat Application to add a validated POST endpoint and test it through Maat’s HTTP kernel.