Finch CLI

The finch command-line tool handles everything outside a running app: scaffolding a new project, installing dependencies, running the dev server, compiling a production binary, and generating boilerplate files. It wraps common Dart commands and adds Finch-specific tasks.

There is a second, separate set of commands available inside a running app (migrate, route, language, info, plus any custom command you register) — those are covered in Commands and are not part of finch -h below. The distinction matters: finch <command> runs before your app exists, while an app-runtime command runs the actual FinchApp instance and can touch routes, the database, and app config. See Running an Application for how the two connect.

Install

dart pub global activate finch

Commands

Run finch -h to see all available commands:

finch -h

✔ templates
        Show the list of available templates
✔ create
        Make new project
        -p, --path       Path of the project
        -n, --name       Name of project
        -d, --docker     Use docker
        -t, --template   Project template [simple, example,...]
✔ get
        Get packages of project, (dart pub get)
✔ runner
        Build runner of project, (dart pub run build_runner build)
✔ run
        Run project, (dart run)
        -p, --path       Path of app file
        -a, --args       Arguments for app file
✔ serve
        Serve project with file watcher
        -p, --path         Path of app file
        -a, --args         Arguments for app file
        -tp, --terminalPort Port for the terminal WebSocket that streams
                            console output and accepts remote commands
                            (default: 8282)
✔ build
        Build Project (dart compile exe)
        -c, --cli        Build for cli
        -a, --appPath    Path of app file
        -l, --langPath   Languages path
        -p, --publicPath Public path
        -w, --widgetPath Widgets path
        -e, --envPath    Envitoment file (.env) path
        -o, --output     Output path
        -t, --type       Type of build (zip, exe)
✔ migrate
        Migrate project to new version of Finch
        -c, --create     Create new project and move files
        -n, --name       Name of migration file (only for create option)
        -s, --sqlite     Migrate SQLite files
✔ test
        Unit test of project, (dart test)
        -r, --reporter   Set how to print test results
✔ make:controller
        Make new controller
        -n, --name       Name of controller
        -p, --path       Path of controller (default: ./lib/controllers/)
✔ make:service
        Make new service
        -n, --name       Name of service
        -p, --path       Path of service (default: ./lib/services/)
✔ make:middleware
        Make new middleware
        -n, --name       Name of middleware
        -p, --path       Path of middleware (default: ./lib/middleware/)
✔ make:migration
        Make new migration
        -n, --name       Name of migration
        -p, --path       Path of migration (default: ./lib/migrations/)
        -s, --sqlite     Create migration for SQLite

        -h, --help       Show the help
        -v, --version    Finch Version
        -u, --update     Update Finch

Note: finch migrate at this top level only supports creating a migration file (--create --name ...); it does not apply pending migrations even with --sqlite. See Running Migrations below for the command that actually runs them.

Common Usage Examples

Create a new project with the example template

finch create -n my_app -t example

See what project templates are available

finch templates

Fetches the list of official templates (each backed by a <template>-finch-docker GitHub repository) that you can pass to finch create -t <key>.

Run the dev server with file watcher

The serve command watches widget and language files and hot-reloads them without restarting the server:

finch serve

Or specify the entry point:

finch serve -p lib/serve.dart

Under the hood, run/serve spawn your app as a child process (dart run [--enable-asserts] [vm-service flags] <path> <args>) and keep a small interactive prompt in your terminal on top of it — press r to restart the child process, c to clear the screen, i to print version/Dart info, h to show your command history, and q to quit. serve additionally opens a WebSocket on --terminalPort (default 8282) that mirrors this same prompt, which is what the local debugger connects to in the browser.

Build a production binary

finch build -a lib/app.dart -o ./build/app

Generate boilerplate files

finch make:controller -n Product
finch make:service -n Payment
finch make:middleware -n RateLimit
finch make:migration -n add_users_table
finch make:migration -n add_users_table -s   # for SQLite instead of MySQL

Create a migration file

finch migrate --create --name add_users_table
finch migrate --create --name add_users_table --sqlite

This only scaffolds a new, empty migration file under your configured migrations path (see Configuration for pathMigrationMySQL/pathMigrationSQLite) — write the actual schema/data changes into it, as described in Database Migration.

Running Migrations

Applying migrations is an app-runtime command, not a top-level finch flag — it has to run inside your actual FinchApp so it can use your configured database connections. Run it by passing --args through finch run/finch serve, or by invoking your app entry point directly with dart run:

# Apply pending MySQL migrations
finch run --args="migrate --init"

# Apply pending SQLite migrations
finch run --args="migrate_sqlite --init"

# Chain both in one call with --and (as used in the example Dockerfile)
finch run --args="migrate --init --and migrate_sqlite --init"

# Equivalent, without going through the finch CLI at all
dart run lib/app.dart migrate --init

See Commands for the full list of app-runtime commands (route, language, info, and any custom command you register) and Database Migration for writing and rolling back migrations.

Inspect registered routes

route is also an app-runtime command, so it's invoked the same way:

# Table view
finch run --args="route"

# With extra columns (controller, function, middlewares, ...)
finch run --args="route --detail"

# As JSON, e.g. to pipe into another tool
finch run --args="route --json"