CLI reference¶
The kivyforge command, also installed as kf, is a group of verbs. Run every
verb from the directory that contains your pyproject.toml. kivyforge looks for
the file in the current directory only, not in parent directories.
The command reference on this page is generated from kivyforge's own command definitions. For how a verb behaves on a specific platform, see that platform's guide.
Target selection¶
Verbs that take -p / --platform resolve the target in this order:
-p/--platformon the command line.- The
KIVYFORGE_PLATFORMenvironment variable. - The host's own platform, if
pyproject.tomlhas an overlay for it. Android and iOS are never a host default, so they always need-porKIVYFORGE_PLATFORM.
If none of these resolves a target, the verb fails and lists the platforms
configured in pyproject.toml. init accepts -p more than once and, without
it, also falls back to the project's only existing overlay. See
Choose a target platform.
Commands¶
kivyforge¶
kivyforge 3.0: build, run, and package Kivy apps for Android, iOS, macOS, Windows, and Linux from one pyproject.toml.
Run commands from the directory that contains your pyproject.toml.
Usage:
kivyforge [OPTIONS] COMMAND [ARGS]...
Options:
| Name | Type | Description | Default |
|---|---|---|---|
-V, --version |
boolean | Show the version and exit. | Sentinel.UNSET |
-h, --help |
boolean | Show this message and exit. | Sentinel.UNSET |
kivyforge build¶
Download artifacts, generate the platform project, and optionally build it.
A bare build only generates the project on iOS and Android: add --simulator, --device or --release (iOS) or --debug (Android) to build it as well.
Usage:
kivyforge build [OPTIONS]
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--platform, -p |
choice (ios | macos | linux | windows | android) |
Target platform (overrides KIVYFORGE_PLATFORM and the host default). | None |
--simulator |
text | Build for the iOS simulator (Debug). | Sentinel.UNSET |
--device |
text | Build for a device (Debug). | Sentinel.UNSET |
--release |
text | Archive + export a .ipa. | Sentinel.UNSET |
--arch |
choice (arm64 | x86_64 | aarch64) |
iOS: simulator arch. macOS: assemble a subset of the locked archs. Linux: which locked arch to assemble (default: the first). | None |
--no-verify-lock |
boolean | Skip the pyproject drift check (CI only). | Sentinel.UNSET |
--no-cache |
boolean | Force re-download of every artifact. | Sentinel.UNSET |
--team-id |
text | iOS: override [tool.kivy.ios.signing].team_id. | None |
--signing-identity |
text | iOS: override [tool.kivy.ios.signing].identity. | None |
--export-method |
choice (app-store | ad-hoc | development) |
iOS (with --release): export method. | app-store |
--debug |
boolean | Android: run Gradle to assemble the debug-signed artifact. Without it, build only generates the Android project. | Sentinel.UNSET |
-f, --format |
choice (apk | aab) |
Android (with --debug): debug artifact format (default apk). | None |
--abi |
choice (arm64_v8a | x86_64) |
Android: restrict this build to one ABI. | None |
--app-version |
text | Build with this version instead of [project].version or the build backend's (also KIVYFORGE_APP_VERSION; the flag wins). | None |
--no-build-isolation |
boolean | Resolve a dynamic version with the build backend installed in kivyforge's own environment (offline) instead of an isolated one. You vouch the environment has everything the backend needs. | Sentinel.UNSET |
--no-color |
boolean | Disable coloured output. NO_COLOR is honoured too. | Sentinel.UNSET |
--json |
boolean | Emit a machine-readable JSON envelope on stdout. | Sentinel.UNSET |
-h, --help |
boolean | Show this message and exit. | Sentinel.UNSET |
kivyforge capabilities¶
List platforms, archs, package formats, and which hosts build what.
Usage:
kivyforge capabilities [OPTIONS]
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--no-color |
boolean | Disable coloured output. NO_COLOR is honoured too. | Sentinel.UNSET |
--json |
boolean | Emit a machine-readable JSON envelope on stdout. | Sentinel.UNSET |
-h, --help |
boolean | Show this message and exit. | Sentinel.UNSET |
kivyforge clean¶
Remove generated artifacts in the project folder.
Usage:
kivyforge clean [OPTIONS]
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--cache |
boolean | Also flush the artifact download cache and the generated Android project's own Gradle cache. pip keeps its own cache, which this leaves alone (pip cache purge clears it). |
Sentinel.UNSET |
--cache-all |
boolean | --cache, plus the shared ~/.gradle caches (affects every project on this machine; the next build re-downloads Gradle's dependencies). | Sentinel.UNSET |
--project-only |
boolean | Only the generated project artifacts, not the artifact cache (default). | False |
--no-color |
boolean | Disable coloured output. NO_COLOR is honoured too. | Sentinel.UNSET |
--json |
boolean | Emit a machine-readable JSON envelope on stdout. | Sentinel.UNSET |
-h, --help |
boolean | Show this message and exit. | Sentinel.UNSET |
kivyforge doctor¶
Run environment and project health checks.
Usage:
kivyforge doctor [OPTIONS]
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--platform, -p |
choice (ios | macos | linux | windows | android) |
Target platform (overrides KIVYFORGE_PLATFORM and the host default). | None |
--offline |
boolean | Skip network-dependent checks. | Sentinel.UNSET |
--no-color |
boolean | Disable coloured output. NO_COLOR is honoured too. | Sentinel.UNSET |
--json |
boolean | Emit a machine-readable JSON envelope on stdout. | Sentinel.UNSET |
-h, --help |
boolean | Show this message and exit. | Sentinel.UNSET |
kivyforge init¶
Seed [tool.kivy] + the target platform's overlay into pyproject.toml.
Usage:
kivyforge init [OPTIONS]
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--platform, -p |
choice (ios | macos | linux | windows | android) |
Target platform. Repeatable to seed several at once, e.g. -p ios -p android (overrides KIVYFORGE_PLATFORM and the host default). Without it: KIVYFORGE_PLATFORM, then the project's one existing overlay, then the host default. | Sentinel.UNSET |
--force |
boolean | Regenerate [tool.kivy*] (preserves signing). | Sentinel.UNSET |
--no-color |
boolean | Disable coloured output. NO_COLOR is honoured too. | Sentinel.UNSET |
--json |
boolean | Emit a machine-readable JSON envelope on stdout. | Sentinel.UNSET |
-h, --help |
boolean | Show this message and exit. | Sentinel.UNSET |
kivyforge lock¶
Generate pylock.
Usage:
kivyforge lock [OPTIONS]
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--platform, -p |
choice (ios | macos | linux | windows | android) |
Target platform (overrides KIVYFORGE_PLATFORM and the host default). | None |
--update |
boolean | Re-resolve even if the lock is in sync. | Sentinel.UNSET |
--offline |
boolean | Use cached resolution results only. | Sentinel.UNSET |
--check |
boolean | CI pre-flight: exit non-zero if the lock is stale; write nothing. | Sentinel.UNSET |
--no-color |
boolean | Disable coloured output. NO_COLOR is honoured too. | Sentinel.UNSET |
--json |
boolean | Emit a machine-readable JSON envelope on stdout. | Sentinel.UNSET |
-h, --help |
boolean | Show this message and exit. | Sentinel.UNSET |
kivyforge open¶
Open the generated project in its IDE: Xcode for iOS, Android Studio for Android.
Usage:
kivyforge open [OPTIONS]
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--platform, -p |
choice (ios | macos | linux | windows | android) |
Target platform (overrides KIVYFORGE_PLATFORM and the host default). | None |
--no-color |
boolean | Disable coloured output. NO_COLOR is honoured too. | Sentinel.UNSET |
--json |
boolean | Emit a machine-readable JSON envelope on stdout. | Sentinel.UNSET |
-h, --help |
boolean | Show this message and exit. | Sentinel.UNSET |
kivyforge package¶
Build the signed, distributable artifact for the resolved platform.
Usage:
kivyforge package [OPTIONS]
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--platform, -p |
choice (ios | macos | linux | windows | android) |
Target platform (overrides KIVYFORGE_PLATFORM and the host default). | None |
-f, --format |
text | Artifact format for the target (defaults to the platform's default). | None |
--arch |
choice (arm64 | x86_64 | aarch64) |
macOS: assemble a subset of the locked archs. Linux: which locked arch to package (default: the first). | None |
--team-id |
text | iOS: override [tool.kivy.ios.signing].team_id. | None |
--signing-identity |
text | iOS and macOS: override [tool.kivy. |
None |
--export-method |
choice (app-store | ad-hoc | development) |
iOS export method. | app-store |
--notarize / --no-notarize |
boolean | macOS: notarize + staple the signed .app (default: when [tool.kivy.macos.signing].notary_profile is configured). | None |
--notary-profile |
text | macOS: override [tool.kivy.macos.signing].notary_profile. | None |
--no-verify-lock |
boolean | Skip the pyproject drift check (CI only). | Sentinel.UNSET |
--no-cache |
boolean | Force re-download of every artifact. | Sentinel.UNSET |
--abi |
choice (arm64_v8a | x86_64) |
Android: restrict this package to one ABI. | None |
--keystore |
text | Android: override [tool.kivy.android.signing].keystore. | None |
--key-alias |
text | Android: override [tool.kivy.android.signing].key_alias. | None |
--app-version |
text | Build with this version instead of [project].version or the build backend's (also KIVYFORGE_APP_VERSION; the flag wins). | None |
--no-build-isolation |
boolean | Resolve a dynamic version with the build backend installed in kivyforge's own environment (offline) instead of an isolated one. You vouch the environment has everything the backend needs. | Sentinel.UNSET |
--no-color |
boolean | Disable coloured output. NO_COLOR is honoured too. | Sentinel.UNSET |
--json |
boolean | Emit a machine-readable JSON envelope on stdout. | Sentinel.UNSET |
-h, --help |
boolean | Show this message and exit. | Sentinel.UNSET |
kivyforge run¶
Build (unless --no-build), install, and launch the app.
Usage:
kivyforge run [OPTIONS]
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--platform, -p |
choice (ios | macos | linux | windows | android) |
Target platform (overrides KIVYFORGE_PLATFORM and the host default). | None |
--simulator |
text | Target the iOS simulator (default). | True |
--device |
text | Target a connected device (Android: a physical one, never an AVD). | Sentinel.UNSET |
--arch |
choice (arm64 | x86_64 | arm64_v8a) |
macOS: a subset of locked archs; Android: restrict to one ABI. | None |
--destination |
text | Specific simulator/device by name or UDID. | None |
--list-devices |
boolean | Print available simulators and devices, then exit. | Sentinel.UNSET |
--no-build |
boolean | Skip the implicit build; install + launch the existing app. | Sentinel.UNSET |
--release |
boolean | Build the release flavor, so byte_compile/strip_source apply as they do for package (Android, Linux, macOS, Windows). Android: the release variant (with --smoke, the release probe). |
Sentinel.UNSET |
--emulator |
boolean | Android: boot/target an emulator (AVD). | Sentinel.UNSET |
--avd |
text | Android: which AVD to boot (--emulator). | None |
--serial |
text | Android: which adb device when several attach. | None |
--smoke |
boolean | Android: run the generated contract smoke test instead of launching. | Sentinel.UNSET |
--abi |
choice (arm64_v8a | x86_64) |
Android: restrict the implicit build to one ABI. | None |
--no-follow |
boolean | Android: print the app's log once, 25 s after launch, and return instead of following it until the app exits or Ctrl-C (for scripts). | Sentinel.UNSET |
--app-version |
text | Build with this version instead of [project].version or the build backend's (also KIVYFORGE_APP_VERSION; the flag wins). | None |
--no-build-isolation |
boolean | Resolve a dynamic version with the build backend installed in kivyforge's own environment (offline) instead of an isolated one. You vouch the environment has everything the backend needs. | Sentinel.UNSET |
-h, --help |
boolean | Show this message and exit. | Sentinel.UNSET |
kivyforge status¶
Show app identity, Python version, lock sync, and build state.
Usage:
kivyforge status [OPTIONS]
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--platform, -p |
choice (ios | macos | linux | windows | android) |
Target platform (overrides KIVYFORGE_PLATFORM and the host default). | None |
--no-color |
boolean | Disable coloured output. NO_COLOR is honoured too. | Sentinel.UNSET |
--json |
boolean | Emit a machine-readable JSON envelope on stdout. | Sentinel.UNSET |
-h, --help |
boolean | Show this message and exit. | Sentinel.UNSET |
kivyforge upgrade¶
Re-fetch pinned runtime/native artifacts for the resolved platform's lock.
Usage:
kivyforge upgrade [OPTIONS]
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--platform, -p |
choice (ios | macos | linux | windows | android) |
Target platform (overrides KIVYFORGE_PLATFORM and the host default). | None |
--python |
boolean | Only refresh the bundled Python runtime (iOS: Python.xcframework; macOS/Linux: the runtime archive(s), where the flag is a no-op because the runtime is already the only refreshable artifact). | Sentinel.UNSET |
--xcframeworks |
boolean | Only refresh native xcframework artifacts (iOS only). | Sentinel.UNSET |
--libs |
boolean | Only refresh the locked .aar/.jar artifacts (Android only); the Android counterpart of --xcframeworks. | Sentinel.UNSET |
--name |
text | Only refresh a specific artifact by name (iOS: an xcframework name or 'Python.xcframework'; Android: an .aar/.jar name or an ABI; macOS/Linux: a locked arch, e.g. 'arm64'). | None |
--no-color |
boolean | Disable coloured output. NO_COLOR is honoured too. | Sentinel.UNSET |
--json |
boolean | Emit a machine-readable JSON envelope on stdout. | Sentinel.UNSET |
-h, --help |
boolean | Show this message and exit. | Sentinel.UNSET |
Platform-specific flags¶
Some flags apply to only some targets. The platform guides explain them in
context. Passing a flag to a target that doesn't use it is an error rather than
being ignored. For example, package -p windows --signing-identity NAME fails
with --signing-identity (ios/macos only) is not valid for windows.
| Target | Flags | Guide |
|---|---|---|
| Android | build: --debug, -f apk\|aab, --abi. run: --emulator, --device, --avd, --serial, --smoke, --abi. package: --keystore, --key-alias, --abi. |
Run on a device or emulator, Sign and publish to Google Play |
| iOS | build: --simulator, --device, --release, --arch, --team-id, --signing-identity, --export-method. run: --simulator, --device, --destination, --list-devices. package: --team-id, --signing-identity, --export-method. |
Run on the simulator or a device, Sign the app |
| macOS | build and package: --arch. package: --signing-identity, --notarize / --no-notarize, --notary-profile. |
Sign, notarize, and staple |
| Linux | build and package: --arch x86_64\|aarch64 (default: the first entry in archs). package: -f appimage\|folder. |
Build an AppImage or folder |
| Windows | None. Configure signing in [tool.kivy.windows.signing]. |
Sign with Authenticode |
For which verb produces which artifact, see Build versus package.
What's next¶
- JSON output for scripts and CI
- Exit and diagnostic codes
- Environment variables