==============
Click Toolbelt
==============

Available commands
==================

Login
-----

Uploading a click package requires the developer to submit
an oauth signed request. For this, click-toolbelt needs to first
obtain an oauth token. In order to do so, the user can run the
following (note: be sure to prepend the command with a space so that
your command history doesn't save the sensitive command).

::

    $   click-toolbelt login <email> <password> [otp]


On successful execution this command will store the oauth credentials
in ``$HOME/.config/click-toolbelt/click.cfg`` and will use it during the
upload step.


Upload
------

Once the user is successfully logged in, he can then upload
the click package. In order to do so, the user can run

::

    $ click-toolbelt upload <binary_file> [--metadata <metadata_file>]


For this command to be successful, certain criteria must be met:

- user must be logged in already (see `Login`_)
- the binary file must be a valid click package
- user owns the application for which he's uploading the click package (if the application already exists)

The ``metadata_file`` parameter should refer to a file containing a json document. If this file is provided,
it will be used to extract extra information not provided in the click package's manifest.

When uploading the initial package, the following fields might be extracted from the ``metadata_file``:

- tagline: A one line summary for the app
- department: The app's category name (see `Department`_)
- channel: The upload target channel name (see `Channel`_). If omitted, 'stable' is assumed.
- support_url: A URL users can go to for support for this application. Allows http(s): and mailto: schemes
- license: The license under which the app will be released (see `License`_)
- icon_256 (or icon): The path to a local file to be uploaded as the icon for the application; the icon must be 256x256 px in size
- name: Application name (overrides what's defined in the click package manifest)
- description: Application description (overrides what's defined in the click package manifest)
- changelog: A description of the changes included since the last upload
- screenshots: A list of paths to local files to be uploaded as screenshots for the application
- blacklist_ids: A list of country codes to prevent the application from being distributed to (see `Country`_)
- whitelist_ids: A list of country codes to limit the application being distributed to (see `Country`_)
- auto_publish: Automatically submit for review
- reviewer_notes: Notes for reviewers to use when reviewing the app's submission

For a new version upload, the ``metadata_file`` file will only be scanned for the following fields:

- channel: The upload target channel name (see `Channel`_). If omitted, 'stable' is assumed.
- changelog: A description of the changes included since the last upload


.. _`Developer Portal`: https://developer.ubuntu.com/


Info
----

The ``info`` command will return metadata about the current available API. To retrieve this data, the user
can run the following command::

    $ click-toolbelt info

This will show all available information about the API. Alternative, the user can retrieve only a subset of the data.

Get the current API version
::

    $ click-toolbelt info version


Get the list of valid license values
::

    $ click-toolbelt info license


Get the list of valid countries
::

    $ click-toolbelt info country


Get the list of valid channels
::

    $ click-toolbelt info channel


Get the list of valid departments
::


    $ click-toolbelt info department


Data values
===========

Department
----------

Valid values can be obtained via the ``info`` command (or it's equivalent api call).

Examples
........

    - "Accessories"
    - "Games"
    - "Card Games"


License
-------

Valid values can be obtained via the ``info`` command (or it's equivalent api call).

Examples
........

    - "Proprietary"
    - "GNU GPL v3"
    - "BSD License (Simplified)"


Country
-------

Valid values can be obtained via the ``info`` command (or it's equivalent api call).

.. note: 

    The ``info`` command will return a list of tuples: (country_code, country_name). The values to be supplied
    in the ``metadata_file`` are *only* the country codes.

Examples
........

    - "AR" (Argentina)
    - "BR" (Brazil)
    - "GB" (United Kingdom)
    - "US" (United States)
    - "UY" (Uruguay)


Channel
-------

Valid values can be obtained via the ``info`` command (or it's equivalent api call).

Examples
........

    - "stable"
    - "proposed"
    - "alpha"
