Commands Overview

The tk-ota-push CLI (alias tkushpatch) is powered by TkOtaPushRunner (lib/src/cli/runner.dart) and addCommonOptions (lib/src/cli/publisher.dart). It exposes 7 subcommands covering authentication, Release and Patch lifecycles, cross-channel promotion, and symbol downloads.

Subcommands Summary Table

Subcommand	Syntax	Purpose	Dedicated Documentation
login	tk-ota-push login [options]	Authenticates the developer workstation via the Web Console (PKCE flow on 127.0.0.1)	Authentication
whoami	tk-ota-push whoami	Displays the logged-in user, Tenant, Subject UUID, roles, and token expiration	Authentication
logout	tk-ota-push logout	Deletes the local session file ~/.tk_ota_push/credentials.json	Authentication
release	tk-ota-push release [version] [options] [-- <flutter-args>]	Builds the app and locks the reference binary (application binary / diff_base) + .symbols	Release
patch	tk-ota-push patch [version] [options] [-- <flutter-args>]	Builds, verifies native integrity, and publishes a differential OTA patch (binary diff + optimized compression)	Patch
promote	tk-ota-push promote --patch-id <uuid> [options]	Promotes an APPROVED_AND_SIGNED patch to another channel without recompiling	Promote
symbols	tk-ota-push symbols --patch-id <uuid> [options]	Downloads the archived .symbols file of a patch to deobfuscate a crash stack trace	Symbols

Global Options

Option	Abbr.	Type	Default	Description (runner.dart)
--help	-h	Flag (negatable: false)	false	Displays general usage information and command options

Common Options for release and patch (addCommonOptions)

These options are registered on both the release and patch subcommands:

Option / Flag	Abbr.	Type	Allowed Values	Default	Description in Code
--platform	-p	Option	android, ios, all	all	Target platform.
--arch	-a	Option	aarch64, arm, all	all	Target architecture (aarch64 for 64-bit, arm for 32-bit, all for both).
--channel	-c	Option	Free string (stable, staging, beta…)	null (resolved to shorebird.yaml or stable)	Target channel (stable, staging, beta - default: read from shorebird.yaml or stable).
--[no-]obfuscate	—	Flag (negatable: true)	true, false	true	Compiles with --obfuscate --split-debug-info and archives .symbols files.
--split-debug-info	—	Option	Directory path	null (build/ota_symbols/<version>)	Directory for .symbols files (default: build/ota_symbols/<version>).
--json	—	Flag (negatable: false)	false	false	Outputs raw JSON response (useful for CI/CD scripts).
--server	—	Option	HTTP/HTTPS URL	null (shorebird.yaml / env / http://localhost:8080)	OTA server URL (default: read from shorebird.yaml, $OTA_SERVER_URL, or localhost:8080).
--tenant-id	—	Option	Identifier	null (shorebird.yaml / session / env / default)	Tenant identifier (default: read from shorebird.yaml or active session).
--app-id	—	Option	Identifier	null (resolution cascade)	app_id (default: read from shorebird.yaml or auto-detected).
--project	—	Option	Directory path	.	Flutter project directory.
--env	-e	Option	String (dev, staging, prod, uat)	null	Application environment (e.g., dev, staging, prod, uat).
--flavor	—	Option	String (dev, staging, prod)	null	Flutter / Gradle / Xcode build flavor (e.g., dev, staging, prod).
--target	-t	Option	.dart file path	null	Specific Dart entry point (e.g., lib/main_dev.dart).
--dart-define	—	MultiOption	KEY=VALUE (repeatable)	[]	Dart environment variables in KEY=VALUE format (repeatable).
--dart-define-from-file	—	MultiOption	.json / .env path (repeatable)	[]	Dart define file .json or .env (repeatable).
--artifact	—	Option	apk, aab, ipa, ios	apk	Artifact type to build (apk or aab for Android, ipa or ios for iOS).
--export-method	—	Option	ad-hoc, app-store, enterprise, development	null	iOS IPA export method (ad-hoc, app-store, etc.).
--export-options-plist	—	Option	.plist file path	null	Path to a custom ExportOptions.plist file for iOS.
--build-name	—	Option	Version x.y.z	null	Alternative Flutter version name (overrides x.y.z in pubspec.yaml).
--build-number	—	Option	Integer / string	null	Alternative Flutter build number (overrides +build in pubspec.yaml).

Positional Arguments and Pass-Through (--)

On release and patch, the first positional argument not starting with - is treated as the explicit version (e.g., 1.0.0+3) and written to pubspec.yaml. All remaining arguments (especially after --) are forwarded directly to flutter build via passThroughArgs.

patch-Specific Options

In addition to the common options above, the patch command accepts:

Option / Flag	Abbr.	Type	Default	Description (runner.dart)
--countries	—	Option	null (fallback shorebird.yaml or worldwide)	Comma-separated ISO-2 country codes (e.g., "CI,SN,CM") or "all" for worldwide (default: worldwide).
--rollout	—	Option	'100'	Rollout percentage (0-100).
--staged	—	Flag (negatable: false)	false	Do not auto-approve: leaves the patch in STAGED state (4-eyes review).
--force	-f	Flag (negatable: false)	false	Forces patch publication even if pubspec.lock changed slightly or if a native code divergence is detected.
--message	-m	Option	null	Business changelog / patch description for security reviewers.

Options Specific to login, promote, and symbols

login Subcommand

Option	Abbr.	Type	Mandatory	Default	Description (runner.dart)
--web-url	—	Option	No	null (shorebird.yaml / $OTA_WEB_CONSOLE_URL / http://localhost:3000)	Web portal URL (default read from shorebird.yaml or http://localhost:3000)
--project	—	Option	No	.	Flutter project path.

promote Subcommand

Option / Flag	Abbr.	Type	Mandatory	Default	Description (runner.dart)
--patch-id	—	Option	Yes (mandatory: true)	—	UUID of the source patch to promote.
--to-channel	—	Option	No	'stable'	Destination channel (e.g., stable).
--tenant-id	—	Option	No	null	Tenant identifier (default: read from shorebird.yaml or active session).
--json	—	Flag (negatable: false)	No	false	Outputs raw JSON response.
--server	—	Option	No	null	OTA server URL (default: read from shorebird.yaml or localhost:8080).
--project	—	Option	No	.	Flutter project path (to read shorebird.yaml).

symbols Subcommand

Option	Abbr.	Type	Mandatory	Default	Description (runner.dart)
--patch-id	—	Option	Yes (mandatory: true)	—	UUID of the patch whose .symbols file should be downloaded.
--output	-o	Option	No	null (patch_<patchId>.symbols)	Output .symbols file path.
--tenant-id	—	Option	No	null	Tenant identifier (default: read from shorebird.yaml or active session).
--server	—	Option	No	null	OTA server URL (default: read from shorebird.yaml or localhost:8080).
--project	—	Option	No	.	Flutter project path (to read shorebird.yaml).

Recognized Environment Variables

Variable	Purpose	Priority
OTA_API_KEY	Bearer token for API / CI authentication	Overrides the local session ~/.tk_ota_push/credentials.json
OTA_SERVER_URL	TkushPatch Server OTA server URL	Used when neither --server nor base_url (shorebird.yaml) is set
SHOREBIRD_BASE_URL	Fallback alias for the OTA server URL	Evaluated right after OTA_SERVER_URL
OTA_TENANT_ID	Tenant identifier	Evaluated after --tenant-id, shorebird.yaml, and session.tenantId
OTA_APP_ID / APP_ID	Application identifier	Evaluated before native Gradle/Xcode detection if not set in shorebird.yaml
OTA_WEB_CONSOLE_URL	Next.js Web Console URL	Used by tk-ota-push login if --web-url and web_console_url are omitted

Exit Codes

The CLI follows POSIX sysexits.h conventions in TkOtaPushRunner.run:

Code	POSIX Constant	Trigger Condition
0	EX_OK	Successful execution, or called with --help, or invoked without arguments (arguments.isEmpty).
1	EXIT_FAILURE	Runtime error: CliException (HTTP 409 conflict, unreachable server, native code divergence, flutter build failure), OtaApiException on promote/symbols, or login failure.
64	EX_USAGE	Command-line syntax error (ArgParser FormatException), unknown subcommand, missing app_id, or --rollout outside 0..100.
66	EX_NOINPUT	Target project directory (--project) does not contain a pubspec.yaml file.
69	EX_UNAVAILABLE	Shorebird toolchain not found in ~/.shorebird/bin/cache/flutter.