Skip to main content

Installation and Setup

The tk-ota-push CLI (also available via the tkushpatch alias) is a pure Dart command-line tool. It compiles Flutter applications using the patched Shorebird toolchain, locks reference binaries during a store release (release), generates and signs differential patches (patch), promotes patches across channels (promote), and downloads obfuscation symbols (symbols).

Technical Prerequisites​

Before installing and running tk-ota-push, make sure your workstation or CI/CD runner meets the following requirements:

ComponentVersion / PathPurpose
Dart SDK>=3.5.4 <4.0.0Running the tk_ota_push CLI and managing dependencies
Shorebird Toolchain~/.shorebird/bin/cache/flutterPatched Flutter engine including flutter, dart, gen_snapshot_arm64, analyze_snapshot_arm64, and aot-tools.dill
Android SDK / GradleRequired for -p androidBuilding .apk and .aab archives
Xcode & Command Line ToolsRequired for -p ios (macOS only)Building Runner.app, .xcarchive bundles, and .ipa exports
curlStandard POSIXUsed on-the-fly on iOS if aot-tools.dill needs to be fetched for the engine revision
Shorebird Toolchain Detection

The Toolchain.locate() class automatically inspects $HOME/.shorebird/bin/cache/flutter (or %USERPROFILE%\.shorebird\bin\cache\flutter on Windows). If this directory is missing or empty, the CLI immediately exits with code 69 (EX_UNAVAILABLE).

Global Installation​

Activate the tk_ota_push package globally using Dart's pub manager:

dart pub global activate tk_ota_push

2. From a local source copy (monorepo / development mode)​

If you are working directly inside the platform repository, activate the CLI from its local path:

dart pub global activate --source path ./tk_ota_push

3. Configuring PATH​

Make sure the Dart global executables directory is included in your PATH environment variable:

  • macOS / Linux (~/.zshrc or ~/.bashrc): 
    export PATH="$PATH":"$HOME/.pub-cache/bin"
  • Windows (PowerShell): 
    $env:Path += ";$env:LOCALAPPDATA\Pub\Cache\bin"

Available Executable Aliases​

The pubspec.yaml file of tk_ota_push declares two strictly equivalent executables pointing to bin/tk_ota_push.dart (TkOtaPushRunner):

executables:
  tk-ota-push: tk_ota_push
  tkushpatch: tk_ota_push

You can also invoke the CLI without global activation if tk_ota_push is listed in your Flutter project's dependencies or dev_dependencies:

# Main executable
tk-ota-push --help

# Short alias
tkushpatch --help

# Direct execution via Dart inside the project
dart run tk_ota_push --help

Verifying the Installation​

To verify that the CLI is properly installed and connected to your environment:

# 1. Display general help and verify the binary
tk-ota-push --help

# 2. Check local session status (~/.tk_ota_push/credentials.json)
tk-ota-push whoami

If no session is active, whoami outputs:

Aucune session active. Lancez `tk-ota-push login`.

Automatic Alignment with the Shorebird Flutter SDK​

When running a release or patch command, the CLI automatically inspects the target project's .dart_tool/package_config.json file. If dependencies were previously resolved with a system Flutter SDK different from the Shorebird toolchain (~/.shorebird/bin/cache/flutter), tk-ota-push automatically runs:

  - Synchronisation automatique des dépendances avec le SDK Flutter Shorebird (flutter pub get)...

Furthermore, every build subprocess is launched with FLUTTER_ROOT and PATH prioritizing the Shorebird toolchain, preventing internal SDK mismatches (such as semantics.dart or sky_engine errors).

Updating and Uninstalling​

To update the CLI to the latest available version:

dart pub global activate tk_ota_push

To uninstall the global executable:

dart pub global deactivate tk_ota_push