Finch CLI

De opdrachtregeltool finch regelt alles buiten een draaiende app: het opzetten van een nieuw project, het installeren van dependencies, het uitvoeren van de ontwikkelserver, het compileren van een productiebinary en het genereren van boilerplate-bestanden. Het omhult veelgebruikte Dart-opdrachten en voegt Finch-specifieke taken toe.

Er is een tweede, aparte set opdrachten beschikbaar binnen een draaiende app (migrate, route, language, info, plus elke aangepaste opdracht die je registreert) — die worden behandeld in Commands en maken geen deel uit van de finch -h-uitvoer hieronder. Het verschil is belangrijk: finch <opdracht> draait voordat je app bestaat, terwijl een app-runtime-opdracht de daadwerkelijke FinchApp-instantie uitvoert en toegang heeft tot routes, de database en app-configuratie. Zie de sectie 'Argumenten doorgeven' in Running an Application voor hoe deze twee met elkaar samenhangen.

Installatie

dart pub global activate finch

Opdrachten

Voer finch -h uit om alle beschikbare opdrachten te zien:

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

Opmerking: finch migrate ondersteunt op dit top-level alleen het aanmaken van een migratiebestand (--create --name ...); het past geen openstaande migraties toe, ook niet met --sqlite. Zie Migraties uitvoeren hieronder voor de opdracht die dit daadwerkelijk doet.

Veelgebruikte voorbeelden

Een nieuw project aanmaken met het example-sjabloon

finch create -n my_app -t example

Bekijk welke projectsjablonen beschikbaar zijn

finch templates

Haalt de lijst met officiële sjablonen op (elk ondersteund door een <template>-finch-docker-GitHub-repository) die je kunt doorgeven aan finch create -t <key>.

De ontwikkelserver starten met bestandswatcher

Het serve-commando bewaakt widget- en taalbestanden en herlaadt ze automatisch zonder de server opnieuw te starten:

finch serve

Of geef het beginpunt op:

finch serve -p lib/serve.dart

Onder de motorkap starten run/serve je app als een child-proces (dart run [--enable-asserts] [vm-service-vlaggen] <path> <args>) en houden ze daarbovenop een kleine interactieve prompt in je terminal — druk op r om het child-proces opnieuw te starten, c om het scherm te wissen, i om versie-/Dart-info weer te geven, h om je opdrachtgeschiedenis te tonen, en q om te stoppen. serve opent daarnaast een WebSocket op --terminalPort (standaard 8282) die dezelfde prompt spiegelt, en waarmee de local debugger in de browser verbinding maakt.

Een productiebinary bouwen

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

Boilerplate-bestanden genereren

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   # voor SQLite in plaats van MySQL

Een migratiebestand aanmaken

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

Dit genereert alleen een nieuw, leeg migratiebestand onder je geconfigureerde migratiepad (zie Configuration voor pathMigrationMySQL/pathMigrationSQLite) — schrijf de daadwerkelijke schema-/datawijzigingen erin, zoals beschreven in Database Migration.

Migraties uitvoeren

Het toepassen van migraties is een app-runtime-opdracht, geen top-level finch-vlag — het moet binnen je daadwerkelijke FinchApp draaien zodat het je geconfigureerde databaseverbindingen kan gebruiken. Voer het uit door --args door te geven via finch run/finch serve, of door je app-entrypoint rechtstreeks aan te roepen met dart run:

# Openstaande MySQL-migraties toepassen
finch run --args="migrate --init"

# Openstaande SQLite-migraties toepassen
finch run --args="migrate_sqlite --init"

# Beide combineren in één aanroep met --and (zoals gebruikt in het voorbeeld-Dockerfile)
finch run --args="migrate --init --and migrate_sqlite --init"

# Equivalent, zonder de finch-CLI te gebruiken
dart run lib/app.dart migrate --init

Zie Commands voor de volledige lijst met app-runtime-opdrachten (route, language, info, en elke aangepaste opdracht die je registreert) en Database Migration voor het schrijven en terugdraaien van migraties.

Geregistreerde routes inspecteren

route is ook een app-runtime-opdracht en wordt daarom op dezelfde manier aangeroepen:

# Tabelweergave
finch run --args="route"

# Met extra kolommen (controller, functie, middlewares, ...)
finch run --args="route --detail"

# Als JSON, bijvoorbeeld om naar een andere tool te pipen
finch run --args="route --json"