nitrogen_cli ⚡ #

CLI tool for Nitrogen plugins. Scaffold, generate, and link Nitrogen FFI plugins from the command line.

⚡ For Nitro docs visit: nitro.shreeman.dev

Installation #

# From this monorepo (local development):
dart pub global activate --source path packages/nitrogen_cli

# Or from pub.dev:
dart pub global activate nitrogen_cli

Add the Dart pub global bin to your PATH (one-time):

# ~/.zshrc or ~/.bashrc:
export PATH="$PATH:$HOME/.pub-cache/bin"

Running nitrogen without arguments launches an interactive TUI dashboard. From there you can init, generate, watch, link, doctor, migrate, clean, and update with live visual feedback. The dashboard also provides one-click Open in VS Code and Open in Antigravity buttons.

nitrogen --version    # print installed version and exit
nitrogen -v           # same

Headless / CI mode #

Every command supports --no-ui. In headless mode all output is plain text prefixed with [nitro], [nitro:warn], or [nitro:error] — no ANSI codes, no interactive prompts.

TTY auto-detection: when stdout is not a terminal (piped output, CI runner), --no-ui activates automatically — you never need to pass it explicitly in CI.

nitrogen <command> --no-ui

Commands #

nitrogen init #

Scaffolds a complete Nitrogen plugin from scratch with pre-wired native configurations.

nitrogen init                                    # interactive TUI form
nitrogen init --name my_plugin                  # skip form, show progress TUI
nitrogen init --no-ui --name my_plugin          # headless / CI
nitrogen init --no-ui --name my_plugin \
              --org com.example \
              --platforms android,ios,macos

Flags:

What it creates:

You only ever edit: the spec, the Kotlin impl, and the Swift impl (or a single C++ impl). Everything else is generated.

nitrogen generate #

Runs flutter pub get + build_runner build, syncs all generated files to their native destinations, then runs nitrogen link inline so you never need to run link separately after a normal generate.

nitrogen generate                          # full generation + link
nitrogen generate --no-ui                  # headless / CI
nitrogen generate --fail-on-warn           # exit 2 on spec warnings
nitrogen generate --dry-run                # preview without writing
nitrogen generate --check                  # exit 3 if outputs are stale
nitrogen generate --targets dart,swift     # restrict output targets
nitrogen generate --verbose                # show per-phase timing

Flags:

--targets aliases:

Exit codes:

Incremental generation: nitrogen generate hashes .native.dart spec files against a cache at .dart_tool/nitro/cache.json. If nothing changed and all outputs exist, build_runner is skipped entirely. The cache is invalidated automatically on any spec modification.

What it produces (per .native.dart spec):

Direct C++ awareness: .bridge.g.swift files that contain only a "Not applicable" placeholder are never copied to ios/Classes/. Instead, the generated .native.g.h headers are synced there so Clang can resolve them during iOS builds.

After generation, nitrogen generate runs the full nitrogen link patching logic inline (CMake, Podspec, Swift, Kotlin, Windows, Linux, .clangd), then runs pod install in every Podfile directory found.

CI examples:

# .github/workflows/build.yml
- name: Generate Nitrogen bindings
  run: |
    dart pub global activate nitrogen_cli
    nitrogen generate --no-ui --fail-on-warn   # exit 2 on spec warnings

- name: Verify bindings are not stale
  run: nitrogen generate --check --no-ui       # exit 3 if stale

nitrogen link #

Wires native build files (CMake, Podspec, Kotlin plugin, Swift plugin, .clangd) to the generated code.

nitrogen link             # interactive TUI with confirmation prompt
nitrogen link --yes       # skip confirmation prompt, show TUI
nitrogen link --no-ui     # headless (implies --yes)

Flags:

What it wires (11 steps):

1. Discovers all modules by scanning lib/**/*.native.dart specs.
2. CMakeLists (src/CMakeLists.txt) — adds NITRO_NATIVE path, dart_api_dl.c, bridge .cpp files, CMAKE_CXX_STANDARD, per-module add_library targets; creates src/HybridXxx.cpp implementation stubs if missing.
3. iOS Podspec — normalises source_files, sets Swift version, iOS deployment target, HEADER_SEARCH_PATHS, DEFINES_MODULE, CLANG_CXX_LANGUAGE_STANDARD, adds s.dependency 'nitro'; copies dart_api_dl.c, nitro.h, and Swift bridges into ios/Classes/; ensures ios/<name>/Package.swift (SPM) exists.
4. macOS Podspec — same as iOS with macOS-specific paths and deployment target.
5. Swift plugin registrars — injects Registry.register(...) calls into ios/*Plugin.swift and macos/*Plugin.swift for Swift/Kotlin modules; removes stale registrations for modules that switched to NativeImpl.cpp.
6. Android Kotlin — injects System.loadLibrary(...) and JniBridge.register(...) into android/.../*Plugin.kt; adds missing imports; removes stale registrations for Android C++ modules.
7. Android Gradle — ensures kotlin.srcDirs includes generated/kotlin.
8. Windows CMakeLists — adds NITRO_NATIVE, dart_api_dl.c, bridge files, include dirs; creates Windows C++ impl stubs in windows/src/ if missing.
9. Linux CMakeLists — same as Windows.
10. .clangd — adds generated/cpp/test/ to IDE compile flags for GoogleMock support when any cpp module exists.
11. Build system finalise — if SPM (Package.swift) is detected, syncs Swift bridges into Sources/ dirs and verifies the FlutterFramework symlink; otherwise runs pod deintegrate + pod install + pod update.

nitrogen doctor #

Deep health check of every layer of your native build. Read-only — no files are changed.

nitrogen doctor           # interactive TUI
nitrogen doctor --no-ui   # headless, one line per check

Flags:

Sections checked:

Direct C++ awareness:

• Android: when all specs use direct C++, Kotlin JNI bridge checks are shown as ℹ info (not required) instead of errors.
• iOS/macOS: Registry.register check skipped; checks for .native.g.h headers in ios/Classes/ instead; no .bridge.g.mm warning.
• Generated files: .bridge.g.kt / .bridge.g.swift shown as ℹ info (placeholder) for cpp modules; .native.g.h, .mock.g.h, .test.g.cpp checked as required outputs.

TUI key bindings (interactive mode):

Exit codes: 0 = all checks pass, 1 = one or more errors.

# .github/workflows/build.yml
- name: Nitrogen health check
  run: |
    dart pub global activate nitrogen_cli
    nitrogen doctor --no-ui   # exits 1 on any error

nitrogen migrate #

Migrates a CocoaPods-only plugin to the Swift Package Manager nested layout (Flutter 3.41+).

nitrogen migrate              # interactive TUI with preview
nitrogen migrate --dry-run    # preview changes without writing files
nitrogen migrate --no-backup  # skip backup step
nitrogen migrate --no-ui      # headless, skips interactive confirmation

Flags:

What it does:

1. Detects current build system state (legacy = CocoaPods-only, mixed = partial SPM, modern = SPM-only). Reports success immediately if already modern.
2. Prompts for confirmation in interactive mode (skipped with --no-ui).
3. Optionally backs up existing ios/*.podspec and example/ios/Podfile into a timestamped .nitrogen_backup_<ts>/ directory.
4. Creates ios/<name>/Package.swift (Flutter 3.41+ nested SPM layout) with Sources/<ClassName>/ (Swift target) and Sources/<ClassName>Cpp/ (C++ target) pointing back to Classes/ via symlinks.
5. Creates macos/<name>/Package.swift when macos/ exists (same structure).
6. Creates the full SPM Sources/ directory structure for both platforms.
7. Cleans up example/ios/Podfile.lock. CocoaPods .podspec files are preserved for backward compatibility.
8. Verifies the new SPM layout is detected correctly.

After migration, run nitrogen link to sync generated files into the new SPM layout.

nitrogen watch #

Runs build_runner watch and automatically re-links generated files on every change. Equivalent to running nitrogen generate on every spec save.

nitrogen watch           # streaming TUI output
nitrogen watch --no-ui   # headless, raw build_runner lines with [nitro] prefix

Flags:

What it does:

1. Kills any running build_runner and removes .dart_tool/build/ to prevent lock-file hangs.
2. Performs an initial nitrogen link sync to ensure all files are wired before watching.
3. Starts a file watcher on the project root (250 ms debounce) that re-links bridge files whenever a .native.dart spec is added, removed, or renamed.
4. Streams build_runner watch --delete-conflicting-outputs output. After each "Succeeded after" line, automatically calls the link sync to copy new Swift bridges into ios/Classes/ / macos/Classes/.
5. Logs "Generation failed. Fix the errors to continue syncing." on "Failed after" lines without exiting — the watcher keeps running.

nitrogen clean #

Deletes all Nitrogen-generated files and the build_runner cache.

nitrogen clean           # interactive output
nitrogen clean --no-ui   # headless

Flags:

What it removes:

• Generated source files: *.g.dart, *.bridge.g.swift, *.bridge.g.kt, *.bridge.g.cpp, *.bridge.g.h, *.bridge.g.mm, *.CMakeLists.g.txt, *.native.g.h, *.mock.g.h, *.test.g.cpp, Hybrid*.hpp, Hybrid*.cpp
• Build caches: .dart_tool/build/lock, .dart_tool/build/asset_graph.json
• Incremental generation cache: .dart_tool/nitro/cache.json

Hidden directories and the build/ output directory are skipped during the file walk.

nitrogen update #

Self-updates the nitrogen CLI to the latest version on pub.dev (or git pull if path-activated).

nitrogen update           # interactive TUI
nitrogen update --no-ui   # headless

Flags:

What it does:

1. Checks the current activation (dart pub global list)
2. Fetches the latest version from pub.dev
3. Runs dart pub global activate nitrogen_cli (hosted) or git pull --ff-only (path-activated)

nitrogen open #

Opens the Nitrogen project root in your editor. In the TUI dashboard this maps to the Open in VS Code and Open in Antigravity buttons. As a CLI command it accepts an --editor flag.

nitrogen open                   # opens in VS Code (default)
nitrogen open --editor code     # explicit VS Code
nitrogen open -e antigravity    # Antigravity (AI-first editor)
nitrogen open --no-ui           # headless

Flags:

What it does: locates the Nitro project root, then runs <editor> <project_path> via the shell. If the editor command is not found in PATH, it prints an error with a hint to add it.

Platform Targeting #

Each platform is configured independently via the @NitroModule annotation. New specs should use the explicit platform constants:

// iOS + Android Swift/Kotlin, macOS via direct C++
@NitroModule(
  lib: 'sensor',
  ios: AppleNativeImpl.swift,
  android: AndroidNativeImpl.kotlin,
  macos: AppleNativeImpl.cpp,
)
abstract class SensorModule extends HybridObject {
  static final SensorModule instance = _SensorModuleImpl();

  bool isReady();
}

// Shared direct C++ implementation everywhere native C++ is supported
@NitroModule(
  lib: 'math',
  ios: AppleNativeImpl.cpp,
  android: AndroidNativeImpl.cpp,
  macos: AppleNativeImpl.cpp,
  windows: WindowsNativeImpl.cpp,
  linux: LinuxNativeImpl.cpp,
)
abstract class Math extends HybridObject {
  static final Math instance = _MathImpl();

  double add(double a, double b);
}

// iOS + macOS Swift, Android Kotlin
@NitroModule(
  lib: 'plugin',
  ios: AppleNativeImpl.swift,
  android: AndroidNativeImpl.kotlin,
  macos: AppleNativeImpl.swift,
)
abstract class MyPlugin extends HybridObject {
  static final MyPlugin instance = _MyPluginImpl();

  String platformVersion();
}

NativeImpl.* remains available as backward-compatible shorthand. The explicit constants are clearer because invalid combinations, such as Kotlin on macOS, are rejected by Dart's type system before generation.

Direct C++ Workflow #

For plugins where both platforms use direct C++:

// lib/src/math.native.dart
@NitroModule(
  lib: 'math',
  ios: AppleNativeImpl.cpp,
  android: AndroidNativeImpl.cpp,
  macos: AppleNativeImpl.cpp,
)
abstract class Math extends HybridObject {
  static final Math instance = _MathImpl();
  double add(double a, double b);
}

nitrogen generate   # → math.native.g.h (abstract C++ interface)
nitrogen link       # → wires CMake, podspec, .clangd

// src/HybridMath.cpp  (you write this)
#include "math.native.g.h"

class HybridMathImpl : public HybridMath {
public:
    double add(double a, double b) override { return a + b; }
};

static HybridMathImpl g_math;

// Auto-register on shared library load — no manual init call needed.
// (Generated by nitrogen link via linkCppImplStubs)
__attribute__((constructor))
static void math_auto_register() {
    math_register_impl(&g_math);
}

nitrogen doctor     # → checks register_impl is wired, headers synced, .clangd up to date

Spec Examples #

Comprehensive type showcase (Swift/Kotlin path) #

// lib/src/sensor.native.dart
import 'package:nitro/nitro.dart';
part 'sensor.g.dart';

// ── Enum ───────────────────────────────────────────────────────────────────
@HybridEnum(startValue: 0)
enum DeviceStatus { idle, busy, error }

// Non-contiguous values (mirror an OS SDK enum):
@HybridEnum(nativeValues: [0, 50, 100])
enum Quality { low, medium, high }

// ── Zero-copy struct (hot-path numeric data) ───────────────────────────────
@HybridStruct(packed: true)
class SensorData {
  final double temperature;
  final double humidity;
  final int timestampMs;
  const SensorData({
    required this.temperature,
    required this.humidity,
    required this.timestampMs,
  });
}

// ── Binary-encoded record (complex / infrequent data) ─────────────────────
@HybridRecord()
class DeviceInfo {
  final String name;
  final DeviceStatus status;
  final List<String> capabilities;
  const DeviceInfo({
    required this.name,
    required this.status,
    required this.capabilities,
  });
}

// ── Discriminated union ───────────────────────────────────────────────────
@NitroVariant()
sealed class ScanResult { const ScanResult(); }

class ScanFound extends ScanResult {
  final DeviceInfo device;
  const ScanFound({required this.device});
}
class ScanTimeout extends ScanResult { const ScanTimeout(); }
class ScanError extends ScanResult {
  final String message;
  const ScanError({required this.message});
}

// ── Named tuple type ──────────────────────────────────────────────────────
@NitroTuple()
typedef SignalStrength = (int, String); // (dbm, label)

// ── Module ────────────────────────────────────────────────────────────────
@NitroModule(
  lib: 'sensor',
  ios: AppleNativeImpl.swift,
  android: AndroidNativeImpl.kotlin,
  macos: AppleNativeImpl.swift,
)
abstract class SensorModule extends HybridObject {
  static final SensorModule instance = _SensorModuleImpl();

  // Synchronous calls
  DeviceStatus getStatus();
  List<DeviceInfo> listDevices();
  void updateSensors(SensorData data);
  SignalStrength getSignal();

  // Nullable return
  DeviceInfo? findDevice(String id);
  int? getLastErrorCode();

  // Async — background isolate (~930 µs overhead)
  @nitroAsync
  Future<List<DeviceInfo>> scanDevices();

  // Native async — native posts result (~146 µs overhead)
  @nitroNativeAsync
  Future<String> connectDevice(String deviceId);

  // Exception-free error result
  @NitroResult()
  @nitroNativeAsync
  Future<NitroResultValue<DeviceInfo>> authenticate(String token);

  // Discriminated union return
  @nitroNativeAsync
  Future<ScanResult> scan(int timeoutMs);

  // Zero-copy buffer
  void sendRawPacket(@zeroCopy Uint8List data);

  // Named param with default
  void configure({Quality quality = Quality.medium, int retryCount = 3});

  // Stream with backpressure
  @NitroStream(backpressure: Backpressure.dropLatest)
  Stream<SensorData> get sensorStream;

  @NitroStream(backpressure: Backpressure.batch, batchMaxSize: 64)
  Stream<double> get audioSamples;

  // Callback parameter
  void onDeviceFound(void Function(DeviceInfo device) callback);
}

Cross-file type sharing #

// lib/src/types.native.dart  ← type-only file, no @NitroModule
import 'package:nitro/nitro.dart';
part 'types.g.dart';

@HybridEnum()
enum Protocol { ble, wifi, usb }

@HybridRecord()
class ConnectionOptions {
  final Protocol protocol;
  final int? timeoutMs;  // nullable int
  const ConnectionOptions({required this.protocol, this.timeoutMs});
}

// lib/src/scanner.native.dart
import 'package:nitro/nitro.dart';
import 'types.native.dart';  // import shared types
part 'scanner.g.dart';

@NitroModule(
  lib: 'scanner',
  ios: AppleNativeImpl.swift,
  android: AndroidNativeImpl.kotlin,
)
abstract class Scanner extends HybridObject {
  static final Scanner instance = _ScannerImpl();

  @nitroNativeAsync
  Future<List<DeviceInfo>> scan(ConnectionOptions options);
}

The generator emits correct #include "types.bridge.g.h" in scanner.bridge.g.h and avoids re-declaring imported types.

Supported Types Quick Reference #

Special Notes #

dart:isolate not needed in spec files (0.5.0+) #

Generated .g.dart files are part of the user's spec and cannot have their own imports. Before 0.5.0, callback specs required import 'dart:isolate' because generated code uses ReceivePort for callback-release ports. As of 0.5.0, package:nitro/nitro.dart re-exports ReceivePort and SendPort conditionally (with a web stub). Remove any manual import from spec files.

// ❌ Before 0.5.0:
import 'dart:isolate';
import 'package:nitro/nitro.dart';
part 'my_module.g.dart';

// ✅ 0.5.0+:
import 'package:nitro/nitro.dart';
part 'my_module.g.dart';

Async overhead comparison #

Known limitations #

Requirements #

Related #

• nitro — Runtime (base classes, annotations, helpers)
• nitro_generator — build_runner code generator
• Getting started guide — step-by-step walkthrough