Add briefcase config Command for User-Level and Global Configuration #2494

MariosLiapis · 2025-10-01T10:19:21Z

Summary

This PR introduces a new Briefcase config command to allow setting and persisting configuration values at both project-specific and global per-user levels. This enables users to define default preferences without modifying pyproject.toml.

This is a second PR attempt for #2279. There was a previous attempt in #2328; because this version adopts a different approach (centralized merge + platforms consume defaults only when the CLI doesn’t specify), I created a new branch/PR.

Currently, many preferences must be hardcoded in pyproject.toml or passed on every invocation. This PR addresses the following gap:

Define author credentials
Define simulator/emulator defaults that briefcase run will use when --device is not provided.

Features

New CLI Command

briefcase config manages user-level configurations. By default it writes to the current project; use --global for setting per-user global configurations.

Supported operations

briefcase config KEY VALUE — set
briefcase config --get KEY — get
briefcase config --unset KEY — unset
briefcase config --list — list the current config file
--global — target the global per-user config instead of the project

Examples

# project-level author credentials
briefcase config author.name "Jane Doe"
briefcase config --global author.email "jane@example.com"

# global-level author credentials
briefcase config --global author.name "Jane Doe"
briefcase config --global author.email "jane@example.com"

# project-level default iOS simulator
briefcase config iOS.device "iPhone 16"

# global default Android emulator
briefcase config --global android.device "emulator-5554"

# get
briefcase config --get iOS.device
briefcase config --global --get android.device

# list
briefcase config --list
briefcase config --global --list

# unset
briefcase config --unset iOS.device
briefcase config --global --unset android.device

# always force device picker on next run
briefcase run android --device "?"

Configuration precedence

Resolved once during command initialization:

CLI overrides > pyproject.toml > project user config > global user config

Storage locations

Project user config: <project>/.briefcase/config.toml
Global user config: platform user config dir (e.g., ~/Library/Application Support/org.beeware.briefcase/config.toml on macOS)

New projects ensure .gitignore contains .briefcase/ to avoid committing per-user files.

Supported keys

android.device — @AVD (e.g., @Pixel_5) or emulator-####
iOS.device — UDID (xxxxxxxx-…-xxxxxxxxxxxx), device name (e.g., "iPhone 16"), or "Name::iOS X[.Y]"

Special value: ? is allowed for both keys to force interactive selection next run.

Not included

Wizard consumption of author.name / author.email (wizard does not read them).
Signing identity defaults (e.g., macOS.identity).
Network/proxy settings or per-app user blocks.

PR Checklist:

All new features have been tested
All new features have been documented
I have read the CONTRIBUTING.md file
I will abide by the code of conduct

…S backends

…ence

…thod stubs to ConfigCommand

…e given keys

…) used in the new wizard; add a function to write .briefcase directory in .gitignore

… errors; allow '?' sentinel for device/identity keys

…et config

…and xcode platform

…eature

freakboy3742

This looks to be broadly on the right track. There's some work needed on the documentation, but the documentation that is there covers all the core details, and it's probably easier for someone closer to the project to do any rewrites to keep the "voice" consistent.

There's also an implied need for a documentation addition - iOS.device and android.device are both properties that need to be added to those backends respective documentation, as based upon this PR, they could be set directly on an app configuration rather than going through global or local configuration.

The other details that is a high level concern is the implemenation of the merge process itself. As flagged inline, the merge process is surprisingly disconnected from the existing config parsing code. There's a lot of seemingly duplicated functionality - briefcase.config already has a merge_config() method; and at the point this block of code is running, we know what platform we're running on. It's not entirely clear to me why new tooling is needed, It seems like much of the functionality for loading and merging should be usable as-is - or, if it can't be, that this is an indicator of a need to refactor the existing tooling.

It also seems like configuration like this should come before parse_config, and be passed into that process as a starting point that the global config is then merged over. It's possible I might be missing something because I'm not actively working on the code, and I've thus missed (or forgotten) the relevant context; if that's the case, let me know.

I haven't reviewed the test code yet - from a quick scan, it looks comprehensive, although some of the test naming seems inconsistent with established patterns. We name test files to track back to the methods that they're testing, rather than their purpose. There's also a lot of duplicated code that feels like it should be in utility classes (or wouldn't be duplicated if the tests were organised by the method they are testing). I'm also surprised that a one line change to device selection requires the addition of 5 additional test files - that seems like the granularity of the tests might be wrong. However, I'll hold off doing a full review of the tests until we know the tests are testing the right thing.

freakboy3742 · 2025-10-03T02:47:55Z

docs/reference/commands/config.rst

+    $ briefcase config --get android.device
+    $ briefcase config --global --get iOS.device
+
+List the current file:


Suggested change

List the current file:

List the current configuration:

freakboy3742 · 2025-10-03T02:51:35Z

src/briefcase/commands/new.py

+if sys.version_info >= (3, 11):  # pragma: no-cover-if-lt-py311
+    pass
+else:  # pragma: no-cover-if-gte-py311
+    pass
+


Isn't this a complete no-op?

freakboy3742 · 2025-10-03T02:52:59Z

src/briefcase/commands/new.py

    return overrides


+def _ensure_gitignore_briefcase(app_path: Path) -> None:


We shouldn't be auto-modifying .gitignore. I've opened beeware/briefcase-template#214 to add .briefcase to the default project.

freakboy3742 · 2025-10-03T02:55:35Z

src/briefcase/integrations/android_sdk.py

+        # Allow "?" to force interactive selection, even if a value was provided
+        if isinstance(device_or_avd, str) and device_or_avd.strip() == "?":


Is the strip() needed here? And if not - does that mean the whole check can simplify to:

Suggested change

# Allow "?" to force interactive selection, even if a value was provided

if isinstance(device_or_avd, str) and device_or_avd.strip() == "?":

# Allow "?" to force interactive selection, even if a value was provided

if device_or_avd == "?":

freakboy3742 · 2025-10-03T02:57:31Z

src/briefcase/platforms/android/gradle.py

+        if isinstance(device_or_avd, str):
+            device_or_avd = device_or_avd.strip()


What case is the strip() catching here? Won't config strings always be precisely terminated?

freakboy3742 · 2025-10-03T03:03:35Z

src/briefcase/platforms/android/gradle.py

+            android_section = getattr(app, "android", None)
+            if isinstance(android_section, dict):
+                configured = android_section.get("device")
+            else:
+                configured = getattr(android_section, "device", None)


This suggests to me to that the structure isn't quite right - it says app.android could be either a dictionary or a Config object. It should be one or the other.

By my read, if we're collapsing configurations correctly, on an Android app, app.device should be set (assuming it's defined at either the global config, project config, or app config level)

freakboy3742 · 2025-10-03T03:04:40Z

src/briefcase/platforms/android/gradle.py

+            raise BriefcaseCommandError(
+                f"Unable to find device or AVD '{device_or_avd}'."
+            ) from e


Why is this additional level of exception handling needed? InvalidDeviceError is a BriefcaseCommandError.

freakboy3742 · 2025-10-03T03:05:17Z

src/briefcase/platforms/iOS/xcode.py

            for the selected device.
        """
+        # Allow "?" to force interactive selection, even if a value was provided
+        if isinstance(udid_or_device, str) and udid_or_device.strip() == "?":


As with Android - should this just be

Suggested change

if isinstance(udid_or_device, str) and udid_or_device.strip() == "?":

if udid_or_device == "?":

freakboy3742 · 2025-10-03T03:05:55Z

src/briefcase/platforms/iOS/xcode.py

+        if udid is None:
+            ios_section = getattr(app, "iOS", {})
+            if isinstance(ios_section, dict):
+                configured = ios_section.get("device")
+            else:
+                configured = getattr(app, "device", None)
+            if configured:
+                udid = configured.strip() or None


As with Android - is this not app.device?

freakboy3742 · 2025-10-03T03:56:38Z

src/briefcase/commands/base.py

+                merged_app_configs = {
+                    name: deep_merge(copy.deepcopy(user_merged), cfg)
+                    for name, cfg in app_configs.items()
+                }


The general approach you've taken here looks about right; however, it concerns me the extent to which the config handling is completely dissociated from the rest of the pyproject.toml config handling.

MariosLiapis added 26 commits September 18, 2025 12:00

Load & merge global and per-project user configsbefore CLI overrides

44e1708

Add 'briefcase config' command for per-user configs

6fb5ace

support ? to force interactive selection across iOS, Android and macO…

726bc54

…S backends

Add new config command in cmdline, __init__ (commands) and .gitignore

babbfa4

Add config command to command options in cmdline.py

d0bcc88

Use per-user default android device in run command, respecting preced…

038ede3

…ence

Fix copy config method in merged_global

ae54669

Small fixes in commands/config.py helper functions; added abstract me…

c98e8ae

…thod stubs to ConfigCommand

Add config.toml to .gitignore

911b8bf

Use per-user default iOS device in respecting precedence

aa14648

Implement new helper function in commands\config.py that validates th…

a9a52b1

…e given keys

Update allowed keys in config.py

ad1941d

Add global user config for author name and email as default (if exist…

43e746e

…) used in the new wizard; add a function to write .briefcase directory in .gitignore

Add functions that resolves identity for macOS platform from config.toml

77afd5a

Replace allowed_keys list; implement key normalizer function to avoid…

ea93862

… errors; allow '?' sentinel for device/identity keys

Update .gitignore file and the function that creates it

97654f2

Implement test suits to honor test coverage

96bcf36

Fix failed tests from config command test suite; implement test for s…

e2aee51

…et config

Remove failing tests

7715aaf

Remove macOS identity handler from config command and its tests

93c2617

Replace old config command test suite

cd7972b

Implement additional tests for commands [base, config, convert, new] …

5572a28

…and xcode platform

Add final tests for complete test coverage

4f83434

Add towncrier fragment and documentation for the new config command f…

ca67ab5

…eature

Remove unneccesary tests

57e144c

Append keywords in docs

e54e389

MariosLiapis marked this pull request as ready for review October 1, 2025 10:56

mhsmith requested a review from freakboy3742 October 2, 2025 11:40

freakboy3742 mentioned this pull request Oct 3, 2025

Add .briefcase to the default gitignore list beeware/briefcase-template#214

Merged

4 tasks

freakboy3742 requested changes Oct 3, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

Add briefcase config Command for User-Level and Global Configuration #2494

Add briefcase config Command for User-Level and Global Configuration #2494

Uh oh!

MariosLiapis commented Oct 1, 2025 •

edited

Loading

Uh oh!

freakboy3742 left a comment

Uh oh!

freakboy3742 Oct 3, 2025

Uh oh!

freakboy3742 Oct 3, 2025

Uh oh!

freakboy3742 Oct 3, 2025

Uh oh!

freakboy3742 Oct 3, 2025

Uh oh!

freakboy3742 Oct 3, 2025

Uh oh!

freakboy3742 Oct 3, 2025

Uh oh!

freakboy3742 Oct 3, 2025

Uh oh!

freakboy3742 Oct 3, 2025

Uh oh!

freakboy3742 Oct 3, 2025

Uh oh!

freakboy3742 Oct 3, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		return overrides


		def _ensure_gitignore_briefcase(app_path: Path) -> None:

		# Allow "?" to force interactive selection, even if a value was provided
		if isinstance(device_or_avd, str) and device_or_avd.strip() == "?":

		if isinstance(device_or_avd, str):
		device_or_avd = device_or_avd.strip()

	if isinstance(udid_or_device, str) and udid_or_device.strip() == "?":
	if udid_or_device == "?":

Uh oh!

Add briefcase config Command for User-Level and Global Configuration #2494

Are you sure you want to change the base?

Add briefcase config Command for User-Level and Global Configuration #2494

Uh oh!

Conversation

MariosLiapis commented Oct 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Features

New CLI Command

Examples

Configuration precedence

Storage locations

Supported keys

Not included

PR Checklist:

Uh oh!

freakboy3742 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

MariosLiapis commented Oct 1, 2025 •

edited

Loading