deeplink_cli

A powerful, developer-friendly Command-Line Interface (CLI) tool to automatically configure, manage, and test custom URL schemes, Android App Links, and iOS Universal Links in your Flutter projects.

Setting up deep links manually is boring and error-prone. deeplink_cli does the heavy lifting for you by editing AndroidManifest.xml, Kotlin/Java MainActivity, Info.plist, and AppDelegate.swift, while generating clean, extensible Dart files to handle incoming links inside your Flutter application.

---

Features

• 🚀 Zero-Config Initialization: Run init and follow interactive prompts to configure everything.
• 📱 Native Configuration: Automatically patches Android Manifest, MainActivity (Kotlin/Java), iOS Info.plist, and AppDelegate (Swift).
• 🔒 App Links & Universal Links: Automatically sets up autoVerify and domain links, generating the required .well-known/ host files (assetlinks.json and apple-app-site-association).
• 🛠️ Diagnostics (doctor): Inspects native files and configurations to diagnose linking issues.
• 🔗 Scheme Management: Add or remove custom URL schemes seamlessly with add-scheme and remove-scheme.
• 🧪 Testing CLI: Launch deep links on a connected Android device/emulator or booted iOS simulator directly from the terminal.
• 🧹 Clean & Restore: Easily restore native files to their pre-cli state with clean using the automatic backup system.

---

Installation

Globally (Recommended)

Activate the package globally to run it from anywhere:

dart pub global activate deeplink_cli

Make sure your Dart SDK's system cache bin directory is in your system's PATH.

As a Dev Dependency

Alternatively, add it to your Flutter project's pubspec.yaml under dev_dependencies:

dev_dependencies:
  deeplink_cli: ^0.1.0

And run it using:

dart run deeplink_cli <command>

---

Quick Start

1. Navigate to the root of your Flutter project.
2. Initialize deep link configuration:

deeplink init

3. Follow the interactive setup prompts:
   • Enter your preferred custom URL scheme (e.g. myapp).
   • Choose whether to generate sample routes and DeepLinkManager Dart code.
   • Choose whether to enable Android App Links and iOS Universal Links (and enter your domain names if enabled).

---

Commands

init

Initializes deep linking configuration for your Flutter project. It will ask interactive questions, create a configuration file (.deeplink_config.json), configure native Android/iOS files, and generate Dart boilerplate files in lib/deep_link/.

deeplink init

doctor

Checks the status of your deep linking configuration and generated native code. It checks for existence of configuration files, backups, native platform edits, and matching parameters.

deeplink doctor

add-scheme

Safely adds an additional custom URL scheme to Android and iOS configurations.

deeplink add-scheme <scheme-name>

remove-scheme

Safely removes a custom URL scheme from Android and iOS configurations.

deeplink remove-scheme <scheme-name>

enable-app-links

Enables Android App Links (autoVerify) and generates the associated .well-known/assetlinks.json file inside the deeplink_setup/ folder.

deeplink enable-app-links [domain1,domain2,...]

enable-universal-links

Enables iOS Universal Links support and generates the associated apple-app-site-association file inside the deeplink_setup/ folder.

deeplink enable-universal-links [domain1,domain2,...]

regenerate

Updates generated Dart code without removing custom user route handlers. Useful when you update your schemes or configurations manually.

deeplink regenerate

test

Tests deep linking integration by launching the URL on a simulator or device.

deeplink test <url>
# Or run without argument to get interactive prompts:
deeplink test

clean

Removes all generated deep linking code, restores native backup files, and cleans configurations.

deeplink clean

---

What files are changed or created?

Native Platform Files (Modified)

• Android:
  • android/app/src/main/AndroidManifest.xml: Injects intent-filters for custom schemes and App Links.
  • android/app/src/main/kotlin/.../MainActivity.kt (or .java): Injects intent handling logic to send deep link intent data to Flutter.
• iOS:
  • ios/Runner/Info.plist: Injects CFBundleURLTypes for custom URL schemes.
  • ios/Runner/AppDelegate.swift: Injects application(_:open:options:) and application(_:continue:restorationHandler:) methods to pass URLs to the Flutter channel.

Generated Flutter Boilerplate (Created)

All Flutter deep link files are generated under lib/deep_link/:

• deep_link_routes.dart: Defines deep link route names and your custom handlers.
• deep_link_constants.dart: Key-value definitions for schemes and paths.
• deep_link_parser.dart: Custom parser helper class.
• deep_link_service.dart: A Dart service listening to platform channels to catch deep link URLs on startup and resume.
• deep_link_manager.dart: Integrates routing logic with your state/navigator.

Asset Setup Files (Created)

Created under deeplink_setup/:

• assetlinks.json: Deployment file for your domain's .well-known/ path (Android).
• apple-app-site-association: Deployment file for your domain's .well-known/ path (iOS).
• setup_instructions.md: Step-by-step details on hosting configurations and web server verification.

---

License

This project is licensed under the MIT License - see the LICENSE file for details.