CLI Reference

Table of Contents#

• Overview
• install
• configure
• doctor
• test
• channels
• uninstall
• publish

Overview#

All Magic Notifications CLI commands are run via a single entry point:

dart run magic_notifications <command> [options]

The CLI is implemented with magic_cli and automatically detects your Flutter project root from pubspec.yaml. Every command that reads or writes project files operates on the detected root, so commands should be run from the project directory or any subdirectory.

install#

Interactive wizard that sets up the full integration: config file, platform files, provider injection, and config factory injection.

dart run magic_notifications install

Flags and Options#

Examples#

# Interactive mode — guided wizard
dart run magic_notifications install

# CI/CD — minimal non-interactive
dart run magic_notifications install \
  --non-interactive \
  --app-id 12345678-1234-1234-1234-123456789012

# CI/CD — full non-interactive with web extras
dart run magic_notifications install \
  --non-interactive \
  --app-id 12345678-1234-1234-1234-123456789012 \
  --platforms android,ios,web \
  --safari-web-id web.onesignal.auto.xxx \
  --notify-button \
  --force

# Disable soft prompt
dart run magic_notifications install --no-soft-prompt

What Install Produces#

1. Creates lib/config/notifications.dart with your App ID and preferences
2. Adds magic_notifications to pubspec.yaml
3. Android: adds POST_NOTIFICATIONS permission to AndroidManifest.xml
4. iOS: adds remote-notification to UIBackgroundModes in ios/Runner/Info.plist, declares aps-environment in ios/Runner/Runner.entitlements (creating the file when the project has never had one), and points CODE_SIGN_ENTITLEMENTS at it in ios/Runner.xcodeproj/project.pbxproj
5. Web: writes web/OneSignalSDKWorker.js, injects SDK <script> into web/index.html
6. Injects NotificationServiceProvider into lib/config/app.dart
7. Injects () => notificationConfig into lib/main.dart

configure#

Read or update individual settings in lib/config/notifications.dart without re-running the full install wizard.

dart run magic_notifications configure [options]

Flags and Options#

Examples#

# Show current config
dart run magic_notifications configure --show

# Update the App ID
dart run magic_notifications configure --app-id 12345678-1234-1234-1234-123456789012

# Change polling to 60 seconds
dart run magic_notifications configure --polling-interval 60

# Disable soft prompt
dart run magic_notifications configure --no-soft-prompt

doctor#

Comprehensive health check that validates plugin installation, configuration, and platform setup. Exits with code 0 when all checks pass, 1 if any check fails.

dart run magic_notifications doctor

Flags and Options#

Examples#

# Basic health check
dart run magic_notifications doctor

# Verbose — shows paths and details
dart run magic_notifications doctor --verbose

Checks Performed#

test#

Send test notifications to verify setup without modifying production data.

dart run magic_notifications test [options]

Flags and Options#

Examples#

# Preview the notification payload (no send)
dart run magic_notifications test --dry-run

# Send a custom database notification
dart run magic_notifications test \
  --title "Hello" \
  --body "World" \
  --channel database

# Send push notification via backend
dart run magic_notifications test \
  --channel push \
  --api-url http://localhost:8000

# Test all channels
dart run magic_notifications test --channel database
dart run magic_notifications test --channel push
dart run magic_notifications test --channel mail

channels#

Display all notification channels and their current configuration status from lib/config/notifications.dart.

dart run magic_notifications channels

This command has no flags. It prints:

• push: driver name, masked App ID (first8chars...), notify button status
• database: enabled status, polling interval in seconds
• mail: enabled status

uninstall#

Remove Magic Notifications integration from the project. Reverses the changes made by install.

dart run magic_notifications uninstall

Flags and Options#

Examples#

# Interactive — shows removal summary and asks for confirmation
dart run magic_notifications uninstall

# Skip confirmation
dart run magic_notifications uninstall --force

What Uninstall Removes#

publish#

Laravel vendor:publish equivalent — copies the default config stub to lib/config/notifications.dart without running any wizard or platform setup.

dart run magic_notifications publish

Flags and Options#

Examples#

# Publish config stub (skips if file already exists)
dart run magic_notifications publish

# Overwrite existing config
dart run magic_notifications publish --force

The published file contains YOUR_ONESIGNAL_APP_ID as a placeholder. After publishing:

1. Replace YOUR_ONESIGNAL_APP_ID with your actual OneSignal App ID (or use String.fromEnvironment)
2. Run dart run magic_notifications install to inject providers and set up platforms

Related

• Installation
• Configuration
• Channels