Skip to main content

Comprehensive CLI Combinations Matrix

This reference page catalogs all valid syntactic combinations supported by the tk-ota-push CLI (alias tkushpatch), categorized by operational intent. Every flag and scenario is validated against the underlying ArgParser implementation (lib/src/cli/runner.dart and publisher.dart).

1. Cross-Reference Options Matrix​

Option / Flagloginwhoamilogoutreleasepatchpromotesymbols
-p, --platform———✅✅——
-a, --arch———✅✅——
-c, --channel———✅✅——
--[no-]obfuscate———✅✅——
--split-debug-info———✅✅——
--json———✅✅✅—
--server———✅✅✅✅
--tenant-id———✅✅✅✅
--app-id———✅✅——
--project✅——✅✅✅✅
-e, --env———✅✅——
--flavor———✅✅——
-t, --target———✅✅——
--dart-define———✅✅——
--dart-define-from-file———✅✅——
--artifact———✅✅——
--export-method———✅✅——
--export-options-plist———✅✅——
--build-name / --build-number———✅✅——
--rollout————✅——
--countries————✅——
--staged————✅——
-f, --force————✅——
-m, --message————✅——
--web-url✅——————
--patch-id—————✅ (required)✅ (required)
--to-channel—————✅—
-o, --output——————✅

2. Authentication and Session Commands​

# 1. Standard interactive browser login (PKCE flow on http://localhost:3000)
tk-ota-push login

# 2. Login with a custom web administration console URL
tk-ota-push login --web-url https://console-ota.enterprise.internal

# 3. Login specifying a project directory
tk-ota-push login --project ./apps/mobile_banking

# 4. Inspect current authenticated identity and session expiry
tk-ota-push whoami

# 5. Logout and remove ~/.tk_ota_push/credentials.json
tk-ota-push logout

3. release Command Combinations​

Android Releases​

# 1. Standard universal APK Release (arm64-v8a + armeabi-v7a)
tk-ota-push release 1.0.0+1 -p android

# 2. Android App Bundle (AAB) Release for Google Play Store
tk-ota-push release 1.0.0+1 -p android --artifact aab

# 3. Multi-flavor Production AAB Release with configuration file injection
tk-ota-push release 1.0.0+1 \
  -p android \
  --flavor prod \
  -t lib/main_prod.dart \
  --artifact aab \
  --dart-define-from-file=env/prod.json

# 4. Android Release strictly targeting 64-bit devices (aarch64 only)
tk-ota-push release 1.0.0+1 -p android -a aarch64

# 5. Release without obfuscation (internal testing or debug builds)
tk-ota-push release 1.0.0+1 -p android --no-obfuscate

# 6. Release saving debug symbols to a custom directory
tk-ota-push release 1.0.0+1 -p android --split-debug-info=build/custom_symbols

# 7. Headless Release with structured JSON output for CI/CD runners
tk-ota-push release 1.0.0+1 -p android --artifact aab --json

iOS Releases​

# 1. Standard iOS Release (inspects Runner.app inside build/ios/iphoneos/)
tk-ota-push release 1.0.0+1 -p ios

# 2. iOS IPA Release with App Store export method
tk-ota-push release 1.0.0+1 -p ios --artifact ipa --export-method app-store

# 3. iOS Ad-Hoc IPA Release with custom ExportOptions.plist
tk-ota-push release 1.0.0+1 \
  -p ios \
  --artifact ipa \
  --export-options-plist ios/ExportOptions.plist \
  --flavor staging \
  -t lib/main_staging.dart

# 4. iOS Release overriding the version name and build number
tk-ota-push release -p ios --build-name 2.0.0 --build-number 150

Unified Multiplatform Releases (Android + iOS)​

# Lock the Release baseline across Android AND iOS in a single run
tk-ota-push release 1.0.0+1 -p all --artifact apk

4. patch Command Combinations​

Progressive Canary Rollouts & Geo-Fencing​

# 1. Immediate 100% worldwide patch on stable channel (default)
tk-ota-push patch 1.0.0+1 -p android -m "Fix balance display glitch"

# 2. Progressive canary rollout targeting 10% of users
tk-ota-push patch 1.0.0+1 -p android --rollout 10 -m "Canary 10% transfer flow"

# 3. Geo-targeted patch restricted to Ivory Coast, Senegal, and Cameroon
tk-ota-push patch 1.0.0+1 -p android --countries "CI,SN,CM" -m "Regional tax rule update"

# 4. Combining 25% rollout with geo-targeting
tk-ota-push patch 1.0.0+1 -p android --rollout 25 --countries "CI,SN" -m "Targeted WAEMU canary"

# 5. Explicitly forcing a worldwide rollout (overriding shorebird.yaml defaults)
tk-ota-push patch 1.0.0+1 -p android --countries "all" -m "Global security fix"

Governance: 4-Eyes Staged Approval & Force Bypass​

# 1. STAGED Patch (4-Eyes principle): published and signed, but held from distribution
tk-ota-push patch 1.0.0+1 -p android --staged -m "Pending CISO approval"

# 2. FORCED Patch (--force): bypasses minor pubspec.lock drift for pure Dart updates
tk-ota-push patch 1.0.0+1 -p android --force -m "Pure Dart intl upgrade"

# 3. Combining --staged and --force
tk-ota-push patch 1.0.0+1 -p android --staged --force -m "Staged dependency bump for QA"

Multi-Flavor, Custom Targets & Multiplatform Patches​

# 1. Android Patch targeting the 'prod' flavor and dedicated entrypoint
tk-ota-push patch 1.0.0+1 \
  -p android \
  --flavor prod \
  -t lib/main_prod.dart \
  --dart-define-from-file=env/prod.json \
  -m "Prod API endpoint patch"

# 2. iOS Patch published directly to the beta channel
tk-ota-push patch 1.0.0+1 -p ios -c beta -m "Fix iOS keyboard layout crash"

# 3. Simultaneous Android + iOS Patch
tk-ota-push patch 1.0.0+1 -p all -m "Cross-platform authentication patch"

5. Promotion and Symbol Management​

# 1. Promote an approved patch from staging to stable
tk-ota-push promote --patch-id 7c9e6679-7425-40de-944b-e07fc1f90ae7 --to-channel stable

# 2. Promote with JSON output for automated audit logs
tk-ota-push promote \
  --patch-id 7c9e6679-7425-40de-944b-e07fc1f90ae7 \
  --to-channel stable \
  --json

# 3. Promote targeting a specific server and tenant
tk-ota-push promote \
  --patch-id 7c9e6679-7425-40de-944b-e07fc1f90ae7 \
  --to-channel stable \
  --server https://ota.banking.internal \
  --tenant-id senegal-subsidiary

# 4. Download obfuscation debug symbols for a given patch
tk-ota-push symbols --patch-id 7c9e6679-7425-40de-944b-e07fc1f90ae7

# 5. Download debug symbols to a specific output path
tk-ota-push symbols \
  --patch-id 7c9e6679-7425-40de-944b-e07fc1f90ae7 \
  -o crash_reports/patch_v13.symbols

# 6. De-obfuscate a production stack trace using downloaded symbols
flutter symbolize -i stacktrace.txt -d crash_reports/patch_v13.symbols