CLI

Quick Reference#

The package has no bin/ of its own. dart run magic:dowel plugin:install magic_deeplink registers MagicDeeplinkDowelProvider in .dowel/plugins.json, and the host app's dowel dispatcher then lists these commands:

dart run magic:dowel list shows what is registered.

Commands#

install#

Runs the manifest in the package's install.yaml through dowel's transactional installer.

dart run magic:dowel deeplink:install
dart run magic:dowel deeplink:install --force
dart run magic:dowel deeplink:install --dry-run

The manifest:

1. Publishes lib/config/deeplink.dart from the bundled stub.
2. Adds DeeplinkServiceProvider and its import to the 'providers' list in lib/config/app.dart.
3. Adds () => deeplinkConfig and import 'config/deeplink.dart'; to the configFactories list in lib/main.dart.
4. Sets FlutterDeepLinkingEnabled to false in ios/Runner/Info.plist.
5. Prints the post-install message.

The command exits with 0 on success or a dry run, and 1 otherwise. It does not edit the Android manifest or register a handler; see Installation.

generate#

Writes the server-side verification files: apple-app-site-association for iOS Universal Links and assetlinks.json for Android App Links.

dart run magic:dowel deeplink:generate \
  --team-id ABCDE12345 \
  --bundle-id com.example.app \
  --package-name com.example.app \
  --sha256-fingerprints "AA:BB:CC:DD:..." \
  --output public/.well-known

Options

Output

Each value falls back to lib/config/deeplink.dart (see Config Merge Strategy). When a platform's values are still missing, that file is skipped with a warning and the command still exits with 0, so one platform's file can be generated on its own.

apple-app-site-association:

{
  "applinks": {
    "details": [
      {
        "appIDs": ["<team-id>.<bundle-id>"],
        "components": [
          { "/": "/*", "comment": "Matches any URL whose path matches /*" }
        ]
      }
    ]
  }
}

assetlinks.json has one entry per fingerprint:

[
  {
    "relation": ["delegate_permission/common.handle_all_urls"],
    "target": {
      "namespace": "android_app",
      "package_name": "com.example.app",
      "sha256_cert_fingerprints": ["AA:BB:CC:DD:..."]
    }
  }
]

doctor#

Checks whether an install actually works, before a device is involved. The manifest installer can publish a file and inject a line, but it cannot place an <intent-filter> inside a specific <activity> or notice a <meta-data> on the wrong element, and every way of getting that half wrong is silent: the link opens the browser, with no exception and no log line.

dart run magic:dowel deeplink:doctor
dart run magic:dowel deeplink:doctor --verbose
dart run magic:dowel deeplink:doctor --remote

What it checks

Local checks, always run:

1. lib/config/deeplink.dart exists and parses with the parser generate uses, and none of domain, team_id, bundle_id, package_name and sha256_fingerprints is still a scaffold placeholder.
2. Dart wiring: DeeplinkServiceProvider appears in lib/config/app.dart and deeplinkConfig in lib/main.dart. A missing registerHandler( call under lib/ is a warning, not a failure, because handlers may be registered somewhere the scan cannot see.
3. iOS, when ios/ exists: FlutterDeepLinkingEnabled is false in Info.plist, and Runner.entitlements carries com.apple.developer.associated-domains with an applinks: host equal to deeplink.domain.
4. Android, when android/ exists: an <intent-filter android:autoVerify="true"> inside an activity carries VIEW, DEFAULT, BROWSABLE, <data> for both http and https, and a host equal to deeplink.domain; and flutter_deeplinking_enabled is false inside <activity>, not <application>. The manifest is read by element position rather than searched as text, because a <meta-data> in the wrong element searches identically to one in the right element and does nothing.
5. The association files exist under web/.well-known/ or public/.well-known/ and agree with the config: the AASA claims <team_id>.<bundle_id>, and assetlinks.json lists the package name and every fingerprint. An AASA that mixes the legacy appID plus paths shape with the appIDs plus components shape is a warning.

Remote check, only with --remote:

6. GET https://<domain>/.well-known/apple-app-site-association and .../assetlinks.json must answer 200 with no redirect and a body that parses as JSON. An AASA served with a content type other than application/json is a warning. The check never runs by default, so the doctor does not hang on DNS in CI or offline.

macOS is not inspected.

What it cannot prove

No check can prove that a device matches a link to this app: swcutil verify needs root and Android verifies at install time. The report says so rather than letting a green run imply it.

Options and exit codes

Config Merge Strategy#

generate and doctor read lib/config/deeplink.dart as text, and generate treats its values as defaults: a flag passed on the command line wins.

--paths defaults to /*, and the config's paths replaces it only while the flag is still exactly that default and the config lists at least one path. A --paths '/*' typed by hand is therefore indistinguishable from no flag, and the config wins. A project can commit every identifier in the config file and run generate with no flags in CI.

The reader matches single-quoted literals with a regular expression, takes the first match in the file, and tolerates a generic type annotation before a list (<String>[...]).

Gotchas#

Related Documentation#

• Installation: the install command and the native setup the doctor checks.
• Configuration: every key of lib/config/deeplink.dart.
• Handlers: registering what the doctor looks for with registerHandler(.
• Magic CLI: the magic:dowel executable that dispatches plugin commands.