==============
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 for an already existing application. In order to do
so, the user can run

::

    $ click-toolbelt upload <namespace>.<app_name> <version> <filename> <changelog> [architecture]


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

    - user is registered as a developer on myapps.developer.ubuntu.com
    - the application has been previously created on myapps.developer.ubuntu.com
    - user owns the application for which he's upload the click package
    - if not specified, architecture will default to 'all'
      (possible values: 'armhf', 'i386', 'amd64', 'all'; you can specify more than one)


Register
--------

While the ``upload`` command works for existing applications, when the developer wants
to register a new application, he can instead use the ``register`` command, like this

::

    $ click-toolbelt register <binary_file> [<source_file>] [<metadata_file>]


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

- user must be logged in already (see `Login`_)
- the binary file must be a valid click package
- the application must not be registered already

The optional ``source_file`` parameter should refer to a compressed file of the full source tree.

The ``metadata_file`` parameter should refer to a file containing a json document. If this file is not provided,
the application will be registered but will remain in a Draft state where manual interaction via
the `Developer Portal`_ is needed before it can be submitted for review.

The ``metadata_file`` file should contain at least the following attributes in order to complete registration:

- tagline: A one line summary for the app
- department: The app's category name (see `Department`_)
- 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

Additionally, it supports the following optional attributes:

- 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

.. _`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 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)
