# 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`). With a name it creates `.//`
  and scaffolds into it; without one it uses the current directory.
  Flag: `--force` to overwrite existing files or scaffold into a
  non-empty directory. See [Configuration](../guides/configuration.md).
- `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](../guides/desktop-preview.md).
- `pn devices [android|ios]`: list connected devices, emulators, and
  simulators with the identifiers `--device` accepts. Flag: `--json` to
  print a JSON array to stdout for scripting; the "no devices" hints go
  to stderr instead, and an empty list prints `[]` and exits 0.
- `pn run android|ios`: build and run on a connected device or
  simulator. Flags: `--device` (target a specific device by identifier
  or name), `--prepare-only`, `--hot-reload`, `--no-logs`.
- `pn logs android|ios`: stream logs from the running app without
  rebuilding.
- `pn build android|ios`: build distributable artifacts (release by
  default). Flags: `--debug` for the debug variant, `--upload` to send
  an iOS release build to App Store Connect. See
  [Building for release](../guides/building-for-release.md).
- `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 --version` (`-V`): print the installed PythonNative version.

::: pythonnative.cli.pn
    options:
      show_root_heading: false
      show_root_toc_entry: false
      members_order: source
      filters: ["!^_"]

## Next steps

- See the [Getting started](../getting-started.md) walkthrough.
- Read about [Hot reload](../guides/hot-reload.md) when you turn on
  `--hot-reload`.