Vue d'ensemble des commandes

La CLI tk-ota-push (alias tkushpatch) s'appuie sur TkOtaPushRunner (lib/src/cli/runner.dart) et addCommonOptions (lib/src/cli/publisher.dart). Elle expose 7 sous-commandes couvrant l'authentification, le cycle de vie des Releases et des Patchs, la promotion inter-canaux et le téléchargement des symboles.

Tableau synthétique des sous-commandes

Sous-commande	Syntaxe	Rôle	Documentation dédiée
login	tk-ota-push login [options]	Connecte le poste développeur via le portail Web (protocole PKCE sur 127.0.0.1)	Authentification
whoami	tk-ota-push whoami	Affiche l'utilisateur connecté, le Tenant, le Subject UUID, les rôles et l'expiration	Authentification
logout	tk-ota-push logout	Supprime le fichier de session locale ~/.tk_ota_push/credentials.json	Authentification
release	tk-ota-push release [version] [options] [-- <flutter-args>]	Compile l'application et verrouille le binaire de référence (binaire d'application / diff_base) + .symbols	Release
patch	tk-ota-push patch [version] [options] [-- <flutter-args>]	Compile, vérifie l'intégrité native et publie un patch OTA différentiel (différentiel binaire + compression optimisée)	Patch
promote	tk-ota-push promote --patch-id <uuid> [options]	Promeut un patch APPROVED_AND_SIGNED vers un autre canal sans recompilation	Promotion
symbols	tk-ota-push symbols --patch-id <uuid> [options]	Télécharge le fichier .symbols archivé d'un patch pour dé-obfusquer une stacktrace	Symboles

Options globales

Option	Abréviation	Type	Défaut	Description exacte (runner.dart)
--help	-h	Flag (negatable: false)	false	Affiche l'aide générale et la liste des options

Options communes à release et patch (addCommonOptions)

Ces options sont enregistrées simultanément sur les sous-commandes release et patch :

Option / Flag	Abrév.	Type	Valeurs autorisées	Défaut	Description exacte dans le code
--platform	-p	Option	android, ios, all	all	Plateforme ciblée.
--arch	-a	Option	aarch64, arm, all	all	Architecture ciblée (aarch64 pour 64-bits, arm pour 32-bits, all pour les deux).
--channel	-c	Option	Chaîne libre (stable, staging, beta…)	null (résolu vers shorebird.yaml ou stable)	Canal (stable, staging, beta - défaut: lu dans shorebird.yaml ou stable).
--[no-]obfuscate	—	Flag (negatable: true)	true, false	true	Compile avec --obfuscate --split-debug-info et archive les fichiers .symbols.
--split-debug-info	—	Option	Chemin de dossier	null (build/ota_symbols/<version>)	Dossier des fichiers .symbols (défaut : build/ota_symbols/<version>).
--json	—	Flag (negatable: false)	false	false	Affiche la réponse brute en JSON (utile pour les scripts CI/CD).
--server	—	Option	URL HTTP/HTTPS	null (shorebird.yaml / env / http://localhost:8080)	URL du serveur OTA (défaut : lu dans shorebird.yaml ou $OTA_SERVER_URL ou localhost:8080).
--tenant-id	—	Option	Identifiant	null (shorebird.yaml / session / env / default)	Identifiant du Tenant (défaut : lu dans shorebird.yaml ou session active).
--app-id	—	Option	Identifiant	null (cascade de résolution)	app_id (défaut : celui de shorebird.yaml).
--project	—	Option	Chemin de dossier	.	Dossier du projet Flutter.
--env	-e	Option	Chaîne (dev, staging, prod, uat)	null	Environnement applicatif (ex: dev, staging, prod, uat).
--flavor	—	Option	Chaîne (dev, staging, prod)	null	Build flavor Flutter / Gradle / Xcode (ex: dev, staging, prod).
--target	-t	Option	Chemin de fichier .dart	null	Point d'entrée Dart spécifique (ex: lib/main_dev.dart).
--dart-define	—	MultiOption	CLE=VALEUR (répétable)	[]	Variables d'environnement Dart au format CLE=VALEUR (répétable).
--dart-define-from-file	—	MultiOption	Chemin .json / .env (répétable)	[]	Fichier de variables Dart .json ou .env (répétable).
--artifact	—	Option	apk, aab, ipa, ios	apk	Type d'artefact à générer (apk ou aab pour Android, ipa ou ios pour iOS).
--export-method	—	Option	ad-hoc, app-store, enterprise, development	null	Méthode d'exportation IPA pour iOS (ad-hoc, app-store, etc.).
--export-options-plist	—	Option	Chemin de fichier .plist	null	Chemin vers un fichier ExportOptions.plist personnalisé pour iOS.
--build-name	—	Option	Version x.y.z	null	Nom de version Flutter alternatif (override x.y.z du pubspec.yaml).
--build-number	—	Option	Entier / chaîne	null	Numéro de build Flutter alternatif (override +build du pubspec.yaml).

Arguments positionnels et Pass-Through (--)

Sur release et patch, le premier argument positionnel ne commençant pas par - est interprété comme la version explicite (ex: 1.0.0+3) et synchronisé dans pubspec.yaml. Tous les autres arguments restants (notamment après --) sont transmis tels quels à flutter build via passThroughArgs.

Options spécifiques à patch

En plus des options communes ci-dessus, la commande patch accepte :

Option / Flag	Abrév.	Type	Défaut	Description exacte (runner.dart)
--countries	—	Option	null (fallback shorebird.yaml ou mondial)	Codes pays ISO-2 autorisés séparés par des virgules (ex: "CI,SN,CM") ou "all" pour mondial (défaut : mondial).
--rollout	—	Option	'100'	Pourcentage de déploiement (0-100).
--staged	—	Flag (negatable: false)	false	Ne pas auto-approuver : le patch reste STAGED (4 yeux).
--force	-f	Flag (negatable: false)	false	Force la publication du patch même si pubspec.lock a légèrement différé (ex: dépendances Dart pures modifiées) ou en cas de divergence native.
--message	-m	Option	null	Changelog / description métier du patch pour le RSSI.

Options spécifiques à login, promote et symbols

Sous-commande login

Option	Abrév.	Type	Obligatoire	Défaut	Description exacte (runner.dart)
--web-url	—	Option	Non	null (shorebird.yaml / $OTA_WEB_CONSOLE_URL / http://localhost:3000)	URL du portail Web (défaut lue dans shorebird.yaml ou http://localhost:3000)
--project	—	Option	Non	.	Chemin du projet Flutter.

Sous-commande promote

Option / Flag	Abrév.	Type	Obligatoire	Défaut	Description exacte (runner.dart)
--patch-id	—	Option	Oui (mandatory: true)	—	Identifiant UUID du patch source à promouvoir.
--to-channel	—	Option	Non	'stable'	Canal de destination (ex: stable).
--tenant-id	—	Option	Non	null	Identifiant du Tenant (défaut : lu dans shorebird.yaml ou session active).
--json	—	Flag (negatable: false)	Non	false	Affiche la réponse brute en JSON.
--server	—	Option	Non	null	URL du serveur OTA (défaut : lu dans shorebird.yaml ou localhost:8080).
--project	—	Option	Non	.	Chemin du projet Flutter (pour lire shorebird.yaml).

Sous-commande symbols

Option	Abrév.	Type	Obligatoire	Défaut	Description exacte (runner.dart)
--patch-id	—	Option	Oui (mandatory: true)	—	Identifiant UUID du patch dont on veut télécharger les .symbols.
--output	-o	Option	Non	null (patch_<patchId>.symbols)	Chemin du fichier .symbols de sortie.
--tenant-id	—	Option	Non	null	Identifiant du Tenant (défaut : lu dans shorebird.yaml ou session active).
--server	—	Option	Non	null	URL du serveur OTA (défaut : lu dans shorebird.yaml ou localhost:8080).
--project	—	Option	Non	.	Chemin du projet Flutter (pour lire shorebird.yaml).

Variables d'environnement reconnues

Variable	Rôle	Priorité
OTA_API_KEY	Jeton Bearer d'authentification API / CI	Outrepasse la session locale ~/.tk_ota_push/credentials.json
OTA_SERVER_URL	URL du serveur OTA Serveur TkushPatch	Utilisée si ni --server ni base_url (shorebird.yaml) ne sont fournis
SHOREBIRD_BASE_URL	Alias de repli pour l'URL du serveur OTA	Utilisée après OTA_SERVER_URL
OTA_TENANT_ID	Identifiant du Tenant	Utilisée après --tenant-id, shorebird.yaml et session.tenantId
OTA_APP_ID / APP_ID	Identifiant de l'application	Utilisée avant la détection native Gradle/Xcode si non défini dans shorebird.yaml
OTA_WEB_CONSOLE_URL	URL de la console Web Next.js	Utilisée par tk-ota-push login si --web-url et web_console_url sont absents

Codes de sortie (Exit Codes)

La CLI respecte les conventions POSIX sysexits.h dans TkOtaPushRunner.run :

Code	Constante POSIX	Condition de déclenchement exacte
0	EX_OK	Exécution réussie, ou appel avec --help, ou appel sans argument (arguments.isEmpty).
1	EXIT_FAILURE	Erreur d'exécution : CliException (conflit HTTP 409, serveur injoignable, divergence native, échec flutter build), OtaApiException sur promote/symbols, ou échec de login.
64	EX_USAGE	Erreur de syntaxe CLI (FormatException de ArgParser), sous-commande inconnue, app_id introuvable, ou --rollout hors de l'intervalle 0..100.
66	EX_NOINPUT	Le répertoire cible (--project) ne contient aucun fichier pubspec.yaml.
69	EX_UNAVAILABLE	Toolchain Shorebird introuvable dans ~/.shorebird/bin/cache/flutter.