Command reference

Common options

The following options are available to all commands:

-C <KEY=VALUE> / --config <KEY=VALUE>

Override the value of an app’s configuration in pyproject.toml with the provided value.

The key will be applied after (and will therefore take precedence over) any platform or backend-specific configuration has been merged into the app’s configuration. The key must be a “top level” TOML key. The use of dotted keys to define nested configuration structures is not permitted.

The value passed to the setting should be valid TOML. If the value being overridden is a string, this means you must quote the value. This may require the use of escape sequences at the command line to ensure the value provided to Briefcase by the shell includes the quotes.

For example, to override the template used by the create command, you can use -C template=..., but the value must be quoted:

briefcase create -C template=\"\"

The only app key that cannot be overridden with -C is app_name, as it is used to identify apps.

-h / --help

Display the available options for the command, and a description of usage.


Always generate a log file. A log file will always be generated if Briefcase doesn’t exit normally; however, it can sometimes be useful to generate a log file when a command has succeeded unsuccessfully. The log file will always contain debug level output, regardless of the -v / --verbosity option specified.


Do not ask the user for input, and use default values. If a safe default behavior exists, that default will be used; otherwise, the command will raise an error.

-v / --verbosity

The verbosity of output generated by Briefcase. -v can be specified multiple times to increase the verbosity:

  • If no flag is specified, Briefcase will generate default output - enough detail to see that progress in a build is being made without being overwhelming.

  • -v generates verbose output. For example, if a command processes a list of files, “normal” verbosity will show a progress bar as those files are processed, but verbose mode will output the name of each file being modified.

  • -vv generates debug output. This will output more internal details of Briefcase operation. This includes the command line, environment, output and return value of every tool and command that Briefcase executes as part of a build.

  • -vvv generates deep debug output. This will include the verbose output of all commands that Briefcase has invoked.

-V / --version

Print the version of Briefcase being used.