DartAPI CLI #

DartAPI is a CLI tool for scaffolding and running typed REST APIs in Dart. It generates a full project structure with routing, JWT authentication, request validation, database integration, and OpenAPI documentation — ready to extend.

Part of the DartAPI ecosystem.

Installation #

dart pub global activate dartapi

Commands #

dartapi create <project_name> #

Scaffolds a new project with:

• bin/main.dart — server entry point
• AuthController, UserController, ProductController — example controllers
• JWT setup via dartapi_auth
• Database connection via dartapi_db
• DTOs with validation
• OpenAPI documentation at /docs

dartapi create my_app
cd my_app
dart pub get
dartapi run --port=8080

dartapi generate controller <Name> #

Adds a typed controller to an existing project:

dartapi generate controller Order

Generates lib/src/controllers/order_controller.dart with GET and POST stubs.

dartapi run --port <port> #

Starts the server and watches for input:

• r — reload
• :q — quit

dartapi run --port=8080

dartapi run --isolates=N #

Spawns N Dart isolates all bound to the same port. The OS load-balances incoming connections across all isolates, utilising every CPU core — the Dart equivalent of Go's goroutine pool.

dartapi run --isolates=4         # 4 isolates, one per core

Each isolate builds its own database connections and handlers — no shared mutable state.

dartapi build #

AOT-compiles the project to a self-contained native binary via dart compile exe. No VM startup cost; single binary deployment like a Go application.

dartapi build                    # produces ./server
dartapi build --output=myapp     # custom binary name
dartapi build --docker           # also writes a Dockerfile

Run the binary:

./server --port=8080

The --docker flag writes a two-stage Dockerfile: compiles in a dart:stable builder image, copies only the binary into a minimal debian:bookworm-slim runtime image.

dartapi build --docker
docker build -t my-app .
docker run -p 8080:8080 my-app

dartapi docs [--port=<port>] [--out=<file>] #

Exports the OpenAPI spec from a running server:

dartapi docs --out openapi.json

dartapi generate migration <name> #

Creates a numbered SQL migration file in migrations/:

dartapi generate migration create_orders_table
# → migrations/0001_create_orders_table.sql

dartapi db migrate #

Runs all pending migrations against the configured database.

Generated Project Structure #

my_app/
├── bin/
│   └── main.dart
├── lib/
│   └── src/
│       ├── core/           # Server and router setup
│       ├── controllers/    # AuthController, UserController, ProductController
│       ├── dto/            # Typed request DTOs
│       ├── db/             # Database connection
│       ├── middleware/     # Auth and logging middleware
│       └── utils/          # Validation helpers
├── pubspec.yaml
└── analysis_options.yaml

Database Setup (optional) #

The generated ProductController requires a PostgreSQL database. If you don't need it, remove ProductController from main.dart.

To use it, update the DbConfig in bin/main.dart:

final config = const DbConfig(
  type: DbType.postgres,
  host: 'localhost',
  port: 5432,
  database: 'dartapi_test',
  username: 'postgres',
  password: 'yourpassword',
  poolConfig: PoolConfig(maxConnections: 10),
);

Then create the products table:

CREATE TABLE products (
  id       SERIAL PRIMARY KEY,
  name     TEXT NOT NULL,
  price    NUMERIC(10, 2) NOT NULL,
  quantity INTEGER NOT NULL
);

API Reference (generated project) #

POST /auth/login #

{ "username": "admin@mail.com", "password": "1234" }

Response:

{ "accessToken": "<jwt>", "refreshToken": "<jwt>" }

POST /auth/refresh #

Body (form-encoded): refresh_token=<token>

Response:

{ "access_token": "<new_jwt>" }

GET /users #

Requires Authorization: Bearer <access_token>.

POST /users #

{ "name": "Jane", "age": 28, "email": "jane@example.com" }

GET /products / POST /products #

Requires Authorization: Bearer <access_token> and a running PostgreSQL database.

POST /products body:

{ "name": "Keyboard", "price": 29.99, "quantity": 15 }

Links #

• dartapi_core — routing, validation, middleware
• dartapi_auth — JWT auth, API key middleware
• dartapi_db — PostgreSQL, MySQL, SQLite
• GitHub
• pub.dev

License #

BSD 3-Clause License © 2025 Akash G Krishnan