.. _ref_commands_login:

login
=====

Login to Charmhub.

Charmcraft will provide a URL for the Charmhub login. When you have
successfully logged in, Charmcraft will store a token for ongoing
access to Charmhub at the CLI (if `--export` option was not used
otherwise it will only save the credentials in the indicated file).

If `--export <file>` option is used, a secret credentials file will
be created. And the file can be used to set `CHARMCRAFT_AUTH`
environment variable.

    export CHARMCRAFT_AUTH=$(cat secret)

This is suitable for Linux environments without a Vault, such as
remote servers and CI/CD pipelines.

Please ensure the secret file and environment variable are secured.

Remember to `charmcraft logout` if you want to remove that token
from your local system, especially in a shared environment.

If the credentials are exported, they can also be attenuated in
several ways specifying their time-to-live (`--ttl`), on which
channels would work (`--channel`), what actions will be able to
do (`--permission`), and on which packages they will work
(using `--charm` or `--bundle`).

See also `charmcraft whoami` to verify that you are logged in.


Usage
-----

:command:`charmcraft login [options]`


Options
-------

``--bundle``
   The bundle(s) on which the required credentials would work (this option can be indicated multiple times; defaults to all).
``--channel``
   The channel(s) on which the required credentials would work (this option can be indicated multiple times, defaults to any channel).
``--charm``
   The charm(s) on which the required credentials would work (this option can be indicated multiple times; defaults to all).
``--export``
   Export the Charmhub unencrypted secret credentials to a file.
``--permission``
   The permission(s) that the required credentials will have (this option can be indicated multiple times, defaults to all permissions).
``--ttl``
   The time-to-live (in seconds) of the required credentials (defaults to 30 hours).

Global options
--------------

``-h`` or ``--help``
   Show this help message and exit.
``-q`` or ``--quiet``
   Only show warnings and errors, not progress.
``-v`` or ``--verbose``
   Show debug information and be more verbose.
``--verbosity``
   Set the verbosity level to 'quiet', 'brief', 'verbose', 'debug' or 'trace'.
``-V`` or ``--version``
   Show the application version and exit.