pythonnative
diff --git a/‎docs/api/cli.md‎
Lines changed: 4 additions & 1 deletion b/‎docs/api/cli.md‎
Lines changed: 4 additions & 1 deletion
diff --git a/‎src/pythonnative/cli/pn.py‎
Lines changed: 36 additions & 6 deletions b/‎src/pythonnative/cli/pn.py‎
Lines changed: 36 additions & 6 deletions
diff --git a/‎tests/test_cli.py‎
Lines changed: 104 additions & 6 deletions b/‎tests/test_cli.py‎
Lines changed: 104 additions & 6 deletions
@@ -57,7 +57,10 @@ the documented behavior never drifts from the code.
   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.
+  or bundle id (iOS), handy for scripts and CI. Flag: `--json` to print
+  a `{"platform": "...", "app_id": "..."}` object to stdout for
+  scripting; the config
+  error goes to stderr instead, and a missing config still exits 1.
 - `pn clean`: remove the local `build/` directory.
 - `pn --version` (`-V`): print the installed PythonNative version.
 
 
@@ -25,7 +25,7 @@
 - `pn build android|ios`: produce standalone artifacts (signed APK/AAB,
   or an iOS archive/IPA, optionally uploaded to App Store Connect).
 - `pn app-id android|ios`: print the resolved application/bundle id
-  (handy for scripts and CI).
+  (handy for scripts and CI), as plain text or as JSON with `--json`.
 - `pn clean`: remove the local `build/` directory.
 
 The heavy lifting lives in the ``pythonnative.project`` and
@@ -343,11 +343,27 @@ def doctor_command(args: argparse.Namespace) -> None:
 def app_id_command(args: argparse.Namespace) -> None:
     """Print the resolved application id (Android) or bundle id (iOS).
 
+    With ``--json``, stdout carries one object,
+    ``{"platform": "...", "app_id": "..."}``, and nothing else; the config
+    error goes to stderr instead so stdout stays parseable. Keys may be
+    added to that object later, but none will be removed or renamed, so
+    a caller reading ``app_id`` keeps working.
+
+    A missing or invalid config still exits 1, with or without the flag.
+    That differs from ``pn devices --json``, which exits 0 on an empty
+    result, because "no devices" is a valid answer to a query whereas
+    an unreadable config means there is no id to report at all.
+
     Args:
-        args: Parsed namespace with ``platform``.
+        args: Parsed namespace with ``platform`` and optional ``json``.
     """
-    config = _load_config_or_exit()
-    print(config.application_id if args.platform == "android" else config.bundle_id)
+    as_json: bool = getattr(args, "json", False)
+    config = _load_config_or_exit(stream=sys.stderr if as_json else None)
+    app_id = config.application_id if args.platform == "android" else config.bundle_id
+    if as_json:
+        print(json.dumps({"platform": args.platform, "app_id": app_id}, indent=2))
+        return
+    print(app_id)
 
 
 # ======================================================================
@@ -981,11 +997,22 @@ def clean_project(args: argparse.Namespace) -> None:
 # ======================================================================
 
 
-def _load_config_or_exit(project_dir: Optional[Path] = None) -> AppConfig:
+def _load_config_or_exit(project_dir: Optional[Path] = None, *, stream: Optional[TextIO] = None) -> AppConfig:
+    """Load the project config or exit 1, reporting the error on ``stream``.
+
+    Args:
+        project_dir: Project root; defaults to the current directory.
+        stream: Where to report a failure. Defaults to stdout, which is
+            what every caller wants except a machine-readable mode, where
+            an error on stdout would corrupt the document.
+
+    Returns:
+        The loaded config.
+    """
     try:
         return AppConfig.load(project_dir or Path.cwd())
     except ConfigError as exc:
-        print(f"Error: {exc}")
+        print(f"Error: {exc}", file=stream or sys.stdout)
         sys.exit(1)
 
 
@@ -1248,6 +1275,9 @@ def _add_server_args(sub: argparse.ArgumentParser) -> None:
 
     parser_app_id = subparsers.add_parser("app-id", help="Print the resolved application/bundle id")
     parser_app_id.add_argument("platform", choices=["android", "ios"], help="Target platform")
+    parser_app_id.add_argument(
+        "--json", action="store_true", help="Print a JSON object to stdout for scripting (errors go to stderr)"
+    )
     parser_app_id.set_defaults(func=app_id_command)
 
     parser_clean = subparsers.add_parser("clean", help="Remove the local build/ directory")
 
@@ -454,13 +454,111 @@ def test_cli_run_without_config_errors() -> None:
         shutil.rmtree(tmpdir, ignore_errors=True)
 
 
-def test_cli_app_id_resolves(tmp_path: Path) -> None:
-    assert run_pn(["init", "my_app"], str(tmp_path)).returncode == 0
-    project_dir = str(tmp_path / "my_app")
-    result = run_pn(["app-id", "android"], project_dir)
+# A default `pn init` scaffold sets only `app.id`, so both platforms resolve to
+# the same string and a test built on it passes with the platform branch
+# inverted. These per-platform overrides make the two diverge.
+_APP_ID_TOML = """\
+[app]
+id = "com.example.base"
+name = "over"
+
+[ios]
+bundle_id = "com.example.ios_override"
+
+[android]
+application_id = "com.example.android_override"
+"""
+
+_EXPECTED_APP_IDS = {
+    "android": "com.example.android_override",
+    "ios": "com.example.ios_override",
+}
+
+
+def _app_id_project(tmp_path: Path) -> str:
+    project_dir = tmp_path / "proj"
+    project_dir.mkdir()
+    (project_dir / "pythonnative.toml").write_text(_APP_ID_TOML, encoding="utf-8")
+    return str(project_dir)
+
+
+@pytest.mark.parametrize("platform", ["android", "ios"])
+def test_cli_app_id_resolves(tmp_path: Path, platform: str) -> None:
+    project_dir = _app_id_project(tmp_path)
+
+    result = run_pn(["app-id", platform], project_dir)
+
+    assert result.returncode == 0, result.stderr
+    # Unstripped, because scripts/run-e2e.sh captures this into a shell
+    # variable: any extra line would corrupt APP_ID and only surface later
+    # as a Maestro failure against a bundle id that doesn't exist.
+    assert result.stdout == f"{_EXPECTED_APP_IDS[platform]}\n"
+    assert result.stderr == ""
+
+
+@pytest.mark.parametrize("platform", ["android", "ios"])
+def test_cli_app_id_json(tmp_path: Path, platform: str) -> None:
+    project_dir = _app_id_project(tmp_path)
+
+    result = run_pn(["app-id", platform, "--json"], project_dir)
+
     assert result.returncode == 0, result.stderr
-    assert result.stdout.strip() == "com.example.my_app"
-    assert run_pn(["app-id", "ios"], project_dir).stdout.strip() == "com.example.my_app"
+    payload = json.loads(result.stdout)
+    assert payload == {"platform": platform, "app_id": _EXPECTED_APP_IDS[platform]}
+    assert result.stderr == ""
+
+
+def test_cli_app_id_json_is_indented(tmp_path: Path) -> None:
+    # json.loads is blind to formatting, so nothing else here would notice
+    # indent=2 being dropped. Scripts consume the bytes, and the docstring
+    # promises an additive-only contract, so pin the exact shape once.
+    project_dir = _app_id_project(tmp_path)
+
+    result = run_pn(["app-id", "android", "--json"], project_dir)
+
+    assert result.stdout == ("{\n" '  "platform": "android",\n' '  "app_id": "com.example.android_override"\n' "}\n")
+
+
+def test_cli_app_id_json_differs_per_platform(tmp_path: Path) -> None:
+    # The pair, so a branch that ignored `platform` would fail even if each
+    # single-platform assertion above were somehow satisfied.
+    project_dir = _app_id_project(tmp_path)
+
+    android = json.loads(run_pn(["app-id", "android", "--json"], project_dir).stdout)
+    ios = json.loads(run_pn(["app-id", "ios", "--json"], project_dir).stdout)
+
+    assert android["app_id"] != ios["app_id"]
+
+
+def test_cli_app_id_json_keeps_errors_off_stdout(tmp_path: Path) -> None:
+    # Without --json this same error goes to stdout, which is why the stream
+    # is scoped rather than global.
+    result = run_pn(["app-id", "android", "--json"], str(tmp_path))
+
+    assert result.returncode == 1
+    assert result.stdout == ""
+    # Match the noun, not the sentence. A malformed config also exits 1 with
+    # an error on stderr, so without this phrase the test passes for either.
+    assert "No pythonnative.toml" in result.stderr
+
+
+def test_cli_app_id_plain_error_stays_on_stdout(tmp_path: Path) -> None:
+    # Pins the scoping: the default path is untouched by the stream change.
+    result = run_pn(["app-id", "android"], str(tmp_path))
+
+    assert result.returncode == 1
+    assert "No pythonnative.toml" in result.stdout
+    assert result.stderr == ""
+
+
+def test_cli_app_id_json_flag_is_wired_through_argparse(tmp_path: Path) -> None:
+    # Everything here goes through run_pn, so argparse is always exercised.
+    # Confirmed rather than assumed: #22 shipped six in-process tests that
+    # all passed with the add_argument deleted.
+    result = run_pn(["app-id", "android", "--json"], str(tmp_path))
+
+    assert result.returncode == 1, "expected the config error, not argparse exit 2"
+    assert "unrecognized arguments" not in result.stderr
 
 
 def test_cli_doctor_runs(tmp_path: Path) -> None: