CLI (pn)

Reference for the pn console script. The implementation lives in pythonnative.cli.pn; this page renders its docstrings directly so the documented behavior never drifts from the code.

Subcommands

• pn init [name]: scaffold a new project (creates app/, pythonnative.toml, .gitignore). Flag: --force to overwrite existing files. See Configuration.
• pn doctor [android|ios]: diagnose the local toolchain and validate pythonnative.toml. Exits non-zero when something will block a build.
• pn preview [component]: render the app in a desktop (Tkinter) window with Fast Refresh — the fastest way to iterate on UI. Flags: --width, --height, --title, --no-hot-reload. See the Desktop preview guide.
• pn run android|ios: build and run on a connected device or simulator. Flags: --prepare-only, --hot-reload, --no-logs.
• pn build android|ios: build distributable artifacts (release by default). Flag: --debug for the debug variant. See Building for release.
• pn app-id android|ios: print the resolved application id (Android) or bundle id (iOS) — handy for scripts and CI.
• pn clean: remove the local build/ directory.

pn CLI: scaffold, diagnose, preview, run, and build PythonNative apps.

The console script pn (declared in pyproject.toml) dispatches to:

• pn init [name]: scaffold a new project (pythonnative.toml + app/).
• pn doctor [platform]: diagnose the local toolchain and config.
• pn preview [component]: render the app in a desktop (Tkinter) window with Fast Refresh — the fast inner dev loop, no device required.
• pn run android|ios: stage + build + install + launch on a device or simulator, with optional on-device hot reload.
• pn build android|ios: produce standalone artifacts (signed APK/AAB, or an iOS archive/IPA).
• pn app-id android|ios: print the resolved application/bundle id (handy for scripts and CI).
• pn clean: remove the local build/ directory.

The heavy lifting lives in the pythonnative.project package; this module is a thin, side-effect-y shell that wires arguments to it and handles the device-facing steps (simulator boot, log streaming, hot reload) that can't be unit tested.

Functions:

Name	Description
init_project	Scaffold a new PythonNative project in the current directory.
doctor_command	Run toolchain/config diagnostics and exit non-zero on errors.
app_id_command	Print the resolved application id (Android) or bundle id (iOS).
preview_project	Render the project in a desktop preview window (Tkinter).
run_project	Stage, build, install, and launch the app on a device/simulator.
build_project	Build standalone, distributable artifacts for platform.
clean_project	Remove the local build/ directory.
main	Entry point for the pn console script.

Attributes:

Name	Type	Description
HOT_RELOAD_DEV_ROOT		Subdirectory (under the app's writable storage) for hot-reload overlays.

HOT_RELOAD_DEV_ROOT module-attribute

HOT_RELOAD_DEV_ROOT = 'pythonnative_dev'

Subdirectory (under the app's writable storage) for hot-reload overlays.

init_project

init_project(args: Namespace) -> None

Scaffold a new PythonNative project in the current directory.

Creates app/main.py, pythonnative.toml, and .gitignore. Refuses to overwrite existing files unless --force is passed.

Parameters:

Name	Type	Description	Default
args	Namespace	Parsed namespace with name (optional) and force.	required

doctor_command

doctor_command(args: Namespace) -> None

Run toolchain/config diagnostics and exit non-zero on errors.

Parameters:

Name	Type	Description	Default
args	Namespace	Parsed namespace with optional platform.	required

app_id_command

app_id_command(args: Namespace) -> None

Print the resolved application id (Android) or bundle id (iOS).

Parameters:

Name	Type	Description	Default
args	Namespace	Parsed namespace with platform.	required

preview_project

preview_project(args: Namespace) -> None

Render the project in a desktop preview window (Tkinter).

Re-execs under PN_PLATFORM=desktop so every module binds to the Tkinter backend, then hands off to pythonnative.preview.run_preview.

Parameters:

Name	Type	Description	Default
args	Namespace	Parsed namespace (component, width, height, title, no_hot_reload).	required

run_project

run_project(args: Namespace) -> None

Stage, build, install, and launch the app on a device/simulator.

Parameters:

Name	Type	Description	Default
args	Namespace	Parsed namespace (platform, prepare_only, hot_reload, no_logs).	required

build_project

build_project(args: Namespace) -> None

Build standalone, distributable artifacts for platform.

Parameters:

Name	Type	Description	Default
args	Namespace	Parsed namespace (platform, debug).	required

clean_project

clean_project(args: Namespace) -> None

Remove the local build/ directory.

Parameters:

Name	Type	Description	Default
args	Namespace	Parsed namespace (unused).	required

main

main() -> None

Entry point for the pn console script.

Next steps

• See the Getting started walkthrough.
• Read about Hot reload when you turn on --hot-reload.