=================
Command reference
=================

.. toctree::
   :maxdepth: 1

   new
   convert
   dev
   create
   update
   build
   run
   package
   publish
   upgrade

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
<https://toml.io/en/v1.0.0#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=\"https://example.com/template\"

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

``-h`` / ``--help``
-------------------

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

``--log``
---------

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.

``--no-input``
--------------

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. Any commands that Briefcase is able to run
  in parallel will be run sequentially.

``-V`` / ``--version``
----------------------

Print the version of Briefcase being used.
