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: ^1.0.0

And run it using:

dart run deeplink_cli <command>

Quick Start

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

deeplink init

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).

Integration in Flutter

Once initialized, integrate deep linking into your Flutter application by performing two simple steps:

Step 1: Initialize the DeepLinkManager

In your app's main file (e.g., lib/main.dart or lib/app/app.dart), initialize the DeepLinkManager inside the root widget's state:

import 'package:flutter/material.dart';
import 'deep_link/deep_link_manager.dart';
import 'deep_link/deep_link_routes.dart';

class MyApp extends StatefulWidget {
  const MyApp({super.key});

  @override
  State<MyApp> createState() => _MyAppState();
}

class _MyAppState extends State<MyApp> {
  late final DeepLinkManager _deepLinkManager;

  @override
  void initState() {
    super.initState();
    // Initialize the manager to start listening to deep links (both cold-starts and runtime links)
    _deepLinkManager = DeepLinkManager()..initialize();
  }

  @override
  void dispose() {
    _deepLinkManager.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      // Pass the generated navigator key to your MaterialApp
      navigatorKey: DeepLinkRoutes.navigatorKey,
      onGenerateRoute: ...
    );
  }
}

Step 2: Configure Route Dispatches

Define what happens when a deep link (e.g., from a scanned QR code) is matched. Open lib/deep_link/deep_link_routes.dart and add navigation logic inside the dispatch function:

import 'package:flutter/material.dart';
import 'deep_link_route.dart';

class DeepLinkRoutes {
  static final GlobalKey<NavigatorState> navigatorKey = GlobalKey<NavigatorState>();

  static void dispatch(DeepLinkRoute route) {
    print('Dispatched deep link: ${route.toString()}');

    // Example handler for a URL like myapp://product/123
    if (route.screen == 'product') {
      final productId = route.pathSegments.length > 1 ? route.pathSegments[1] : null;
      if (productId != null) {
        navigatorKey.currentState?.pushNamed('/product', arguments: productId);
      }
    }
  }
}

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.