katana_cli 3.33.0

Command line tool for Masamune/Katana Framework. It initializes the project and initializes the services.

Katana CLI

---

[GitHub] | [YouTube] | [Packages] | [X] | [LinkedIn] | [mathru.net]

---

Command line interface used in the Masamune framework.

The following features are available

• Project creation and optimization against the Masamune framework
• Code template generation
• Automatic code generation with build_runner
• Other settings

Installation

Install with the following command.

flutter pub global activate katana_cli

Check the dependencies of the commands used internally. If these do not all pass, it may not work properly.

katana doctor

How to use

The following commands are available

katana [command] [subcommand] [optional parameters]

Help for the command is available at

katana help

Project Creation

Execute the following command in the folder where the project was created.

The Application ID should include the ID in the reverse domain (com.test.myapplication).

katana create [Application ID(e.g. com.test.myapplication)]

Code generation

The following commands can be used to generate each code template.

katana code [Code ID] [Optional Parameters]

Page

Create page templates under lib/pages.

katana code page [PageName]

Collection Model

Create a collection model under lib/models.

katana code collection [ModelName]

Document Model

Create a document model under lib/models.

katana code document [ModelName]

Controller

Create controllers under lib/controllers.

katana code controller [ControllerName]

For other codes, please see Help.

Masamune AI Debugger

Add the AI Debugger dependency, configure all flavor dart-defines, and register one adapter instance in a standard Masamune project.

katana code debuggable

Automatic code generation with build_runner

You must have build_runner installed in your project in order to run it.

flutter pub add --dev build_runner

Development and production environments

New projects use dart_defines/dev.env and dart_defines/prod.env. Run Flutter with --dart-define-from-file; Flutter's native --flavor option and the legacy katana flavor pre-copy workflow are not required.

flutter run --dart-define-from-file=dart_defines/dev.env
flutter build appbundle --dart-define-from-file=dart_defines/prod.env
katana apply --flavor dev
katana deploy --flavor prod

FLAVOR must be dev or prod. Android may optionally set ANDROID_APPLICATION_ID; otherwise Android, iOS, and macOS keep the common ID created by katana compose. Firebase configuration and Wrangler bindings are selected with the same FLAVOR. Worker endpoints remain explicit Dart adapter parameters and are never written to dart-defines.

Run katana apply --flavor dev and katana apply --flavor prod once for each environment. The order does not matter and reapplying one environment preserves the other environment. Cloudflare keeps both projects in one wrangler.jsonc under env.dev and env.prod. Firebase shares the deploy configuration in firebase/firebase.json and stores both project mappings as dev and prod aliases in firebase/.firebaserc. Katana commands also pass the resolved project or environment explicitly, so they do not depend on the Firebase default alias or Wrangler's top-level environment. Wrangler's top-level Worker name is kept fixed to the production/base project so applying dev does not rewrite it. When running Wrangler directly, always pass --env dev or --env prod; use katana deploy --flavor <flavor> for the guarded deployment flow.

Existing projects can be inspected without changes and migrated explicitly:

katana fix
katana fix --dry-run
katana fix --apply

Create Firebase and Cloudflare projects before running apply. Katana does not create those projects automatically.

Automatic code generation

If you want to perform automatic code generation as a one-shot, execute the following command.

katana code generate

Code generation monitoring

If you want to monitor code changes and automatically generate code when changes are made, execute the following command.

katana code watch

For other commands, please see Help.

GitHub Sponsors

Sponsors are always welcome. Thank you for your support!

https://github.com/sponsors/mathrunet

Location during an active session

location.enable_background controls the native background location capability. location.require_always_permission defaults to true for compatibility. Set it to false to keep that capability with WhenInUse authorization only:

location:
  enable: true
  enable_background: true
  require_always_permission: false
  permission:
    en: Location is used during playback to adapt your soundtrack.

Apply the setting with katana apply --local --only location --flavor dev when location dependencies and backend initialization already exist. The action removes obsolete Always usage messages and Android background location permission, preserves iOS background modes, enables Android location foreground service permissions, and synchronizes the permission_handler/geolocator iOS compilation flags. Reapplying or switching back to Always access is supported. The application must start location updates while visible, stop them when its active session ends, and handle denied permissions independently.

Migrating deep links to a custom scheme

Use app.deeplink.remove_hosts to remove dedicated Android VIEW filters and iOS applinks entries for explicitly listed HTTP(S) origins. Other URL handlers and entitlements remain unchanged. Mixed Android filters are preserved; separate unrelated origins before using this migration.

app:
  deeplink:
    enable: true
    host: segue://track
    remove_hosts:
      - https://segue.day

Run katana apply --only deeplink to apply only the deep link settings. Existing custom-scheme handlers remain available. Update the hosted association documents separately when public HTTPS links should open a web page first.