Run the app

Implementation

1. Recommended: always use kasy run (or the MCP). It's the complete path: loads credentials, shows the Kasy brand, and warns you when a CLI update is available.

   Via MCP: ask "run the app". The assistant asks for the platform (iOS, Android, or web) and, on web, whether you want only the URL, the default browser (openBrowser), or Flutter's isolated Chrome (flutterChrome). For a fresh onboarding test on web, use freshStorage or clear_web_storage. See Kasy MCP.

   Via terminal:

   cd your_app
   kasy run                 # first available device
   kasy run --ios           # iOS simulator
   kasy run --android       # Android emulator
   kasy run --web           # web at localhost:5555
   kasy run --web --open-browser --fresh   # default browser, storage cleared
   kasy run --web --open    # Flutter's isolated Chrome
   kasy clear-web           # clear storage only (app must already be running)
   kasy run --prod          # uses launch.json's production config

2. To validate the first-open flow (push, onboarding, ATT, Face ID), run:

   Via MCP: "reset the app on iOS" (reset_app).

   Via terminal:

   kasy reset               # detects the device, asks if there's more than one
   kasy reset --ios
   kasy reset --android
   kasy reset --web         # clears dev storage in the browser (needs kasy run --web running)
   kasy reset -d <device-id>   # specific device (ID from flutter devices)
   kasy reset --no-reinstall   # only uninstalls

   Uninstalls the app from the simulator/emulator and reinstalls it right after. A plain flutter run keeps the data and permissions already granted, so it doesn't work for this test (details in Information).

3. When you're ready for a release build:

   flutter build ipa --release --dart-define=ENV=prod
   # or simply:
   kasy ios release   # already injects ENV=prod and bumps the build

   Via MCP: "publish iOS" (release_ios). See Kasy MCP.

Next step: see the app running.

Information

Why not just flutter run?

Automatic RevenueCat key

RevenueCat has three key types, and each one only works in one place:

kasy run detects the device and injects the right key from the .env. You don't have to remember which one goes where.

RC_TEST_KEY=test_xxx
RC_IOS_PROD_KEY=appl_xxx
RC_ANDROID_PROD_KEY=goog_xxx

Web: which variant to pick

All of them run the same build and show the same screen, with the device preview frame included. The difference is only which window hosts the page:

On the web, login stores the session by origin (domain + port), whether Supabase Auth or Firebase Auth. That's why the port is pinned at 5555: if it changed on every run, the login would seem to vanish.

If 5555 is already in use: kasy run --web --web-port 6000.

Initial screen in debug

kasy run may open on the last screen you were on (e.g., admin, components). This helps day-to-day work and hot restart (R). This isn't production behavior: in release, the app starts at Home (native) or at the URL the user opened (web). Details in Navigation → debug vs production.

Other ways (they work)

make run           # without the CLI installed globally
flutter run        # faster; uses the .env but without kasy run's extras

In VS Code, F5 uses .vscode/launch.json (with a graphical debugger).

Full log for debugging errors

kasy run records all of Flutter's output to .kasy/run.log. Paste that file to an AI when you need help.

To see the raw output directly in the terminal:

kasy run --raw           # raw output, no spinner
kasy run | tee out.log   # any pipe already falls back to raw mode automatically

What kasy reset clears on each platform

iOS Keychain persists by Apple's design, the same way WhatsApp "remembers" you after a reinstall. To test without an account on a physical device: sign out inside the app itself.

How to test "from scratch" on a physical iPhone

Where kasy reset shines: on the iOS simulator and Android emulator, where it wipes everything (including permissions) in seconds.

Last updated on 08/02/2026