ansible/docs/man/man1/ansible-galaxy.1.asciidoc.in

ansible-galaxy(1)
===================
:doctype:      manpage
:man source:   Ansible
:man version:  %VERSION%
:man manual:   System administration commands

NAME
----
ansible-galaxy - manage roles using galaxy.ansible.com


SYNOPSIS
--------
ansible-galaxy [delete|import|info|init|install|list|login|remove|search|setup] [--help] [options] ...


DESCRIPTION
-----------

*Ansible Galaxy* is a shared repository for Ansible roles.
The ansible-galaxy command can be used to manage these roles,
or for creating a skeleton framework for roles you'd like to upload to Galaxy.

COMMON OPTIONS
--------------

*-h*, *--help*::

Show a help message related to the given sub-command.

INSTALL
-------

The *install* sub-command is used to install roles.

USAGE
~~~~~

$ ansible-galaxy install [options] [-r FILE | role_name(s)[,version] | tar_file(s)]

Roles can be installed in several different ways:

* A username.rolename[,version] - this will install a single role. The Galaxy
  API will be contacted to provide the information about the role, and the
  corresponding .tar.gz will be downloaded from *github.com*. If the version
  is omitted, the most recent version available will be installed.

* A file name, using *-r* - this will install multiple roles listed one per
  line. The format of each line is the same as above: username.rolename[,version]

* A .tar.gz of a valid role you've downloaded directly from *github.com*. This
  is mainly useful when the system running Ansible does not have access to
  the Galaxy API, for instance when behind a firewall or proxy.


OPTIONS
~~~~~~~

*-f*, *--force*::

Force overwriting an existing role.

*-i*, *--ignore-errors*::

Ignore errors and continue with the next specified role.

*-n*, *--no-deps*::

Don't download roles listed as dependencies.

*-p* 'ROLES_PATH', *--roles-path=*'ROLES_PATH'::

The path to the directory containing your roles. The default is the *roles_path* 
configured in your *ansible.cfg* file (/etc/ansible/roles if not configured)

*-r* 'ROLE_FILE', *--role-file=*'ROLE_FILE'::

A file containing a list of roles to be imported, as specified above. This
option cannot be used if a rolename or .tar.gz have been specified.

REMOVE
------

The *remove* sub-command is used to remove one or more roles.

USAGE
~~~~~

$ ansible-galaxy remove role1 role2 ...

OPTIONS
~~~~~~~

*-p* 'ROLES_PATH', *--roles-path=*'ROLES_PATH'::

The path to the directory containing your roles. The default is the *roles_path* 
configured in your *ansible.cfg* file (/etc/ansible/roles if not configured)

INIT
----

The *init* command is used to create a new role suitable for uploading
to https://galaxy.ansible.com (or for roles in general). Creates a skeleton
directory structure and default files.

USAGE
~~~~~

$ ansible-galaxy init [options] role_name

OPTIONS
~~~~~~~

*-f*, *--force*::

Force overwriting an existing role.

*-p* 'INIT_PATH', *--init-path=*'INIT_PATH'::

The path in which the skeleton role will be created.The default is the current 
working directory.

*--offline*::

Don't query the galaxy API when creating roles

*--container-enabled*::

Initialize the new role with files appropriate for a Container Enabled role.

LIST
----

The *list* sub-command is used to show what roles are currently installed.
You can specify a role name, and if installed only that role will be shown.

USAGE
~~~~~

$ ansible-galaxy list [role_name]

OPTIONS
~~~~~~~

*-p* 'ROLES_PATH', *--roles-path=*'ROLES_PATH'::

The path to the directory containing your roles. The default is the *roles_path*
configured in your *ansible.cfg* file (/etc/ansible/roles if not configured)


SEARCH
------

The *search* sub-command returns a filtered list of roles found on the remote
server.


USAGE
~~~~~

$ ansible-galaxy search [options] [searchterm1 searchterm2]


OPTIONS
~~~~~~~
*--galaxy-tags*::

Provide a comma separated list of Galaxy Tags on which to filter.

*--platforms*::

Provide a comma separated list of Platforms on which to filter.

*--author*::

Specify the username of a Galaxy contributor on which to filter.

*-c*, *--ignore-certs*::

Ignore TLS certificate errors. 

*-s*, *--server*::

Override the default server https://galaxy.ansible.com.


INFO
----

The *info* sub-command shows detailed information for a specific role.
Details returned about the role included information from the local copy
as well as information from galaxy.ansible.com.

USAGE
~~~~~

$ ansible-galaxy info [options] role_name[, version]

OPTIONS
~~~~~~~

*-p* 'ROLES_PATH', *--roles-path=*'ROLES_PATH'::

The path to the directory containing your roles. The default is the *roles_path* 
configured in your *ansible.cfg* file (/etc/ansible/roles if not configured)

*-c*, *--ignore-certs*::

Ignore TLS certificate errors. 

*-s*, *--server*::

Override the default server https://galaxy.ansible.com.


LOGIN
-----

The *login* sub-command is used to authenticate with galaxy.ansible.com. 
Authentication is required to use the import, delete and setup commands.
It will authenticate the user, retrieve a token from Galaxy, and store it
in the user's home directory.

USAGE
~~~~~

$ ansible-galaxy login [options]

The *login* sub-command prompts for a *GitHub* username and password. It does
NOT send your password to Galaxy. It actually authenticates with GitHub and
creates a personal access token. It then sends the personal access token to
Galaxy, which in turn verifies that you are you and returns a Galaxy access
token. After authentication completes the *GitHub* personal access token is
destroyed. 

If you do not wish to use your GitHub password, or if you have two-factor
authentication enabled with GitHub, use the *--github-token* option to pass a
personal access token that you create. Log into GitHub, go to Settings and
click on Personal Access Token to create a token.

OPTIONS
~~~~~~~

*-c*, *--ignore-certs*::

Ignore TLS certificate errors. 

*-s*, *--server*::

Override the default server https://galaxy.ansible.com.

*--github-token*::

Authenticate using a *GitHub* personal access token rather than a password.


IMPORT
------

Import a role from *GitHub* to galaxy.ansible.com. Requires the user first
authenticate with galaxy.ansible.com using the *login* subcommand.

USAGE
~~~~~

$ ansible-galaxy import [options] github_user github_repo

OPTIONS
~~~~~~~
*-c*, *--ignore-certs*::

Ignore TLS certificate errors. 

*-s*, *--server*::

Override the default server https://galaxy.ansible.com.

*--branch*::

Provide a specific branch to import. When a branch is not specified the
branch found in meta/main.yml is used. If no branch is specified in
meta/main.yml, the repo's default branch (usually master) is used.

*--role-name*::

Set the name of the role. Otherwise, the name is derived from the
name of the GitHub repository.

DELETE
------

The *delete* sub-command will delete a role from galaxy.ansible.com. Requires
the user first authenticate with galaxy.ansible.com using the *login* subcommand.

USAGE
~~~~~

$ ansible-galaxy delete [options] github_user github_repo

OPTIONS
~~~~~~~

*-c*, *--ignore-certs*::

Ignore TLS certificate errors. 

*-s*, *--server*::

Override the default server https://galaxy.ansible.com.


SETUP
-----

The *setup* sub-command creates an integration point for *Travis CI*, enabling 
galaxy.ansible.com to receive notifications from *Travis* on build completion.
Requires the user first authenticate with galaxy.ansible.com using the *login*
subcommand.

USAGE
~~~~~

$ ansible-galaxy setup [options] source github_user github_repo secret

* Use *travis* as the source value. In the future additional source values may
  be added.

* Provide your *Travis* user token as the secret. The token is not stored by
  galaxy.ansible.com. A hash is created using github_user, github_repo
  and your token. The hash value is what actually gets stored.

OPTIONS
~~~~~~~

*-c*, *--ignore-certs*::

Ignore TLS certificate errors. 

*-s*, *--server*::

Override the default server https://galaxy.ansible.com.

--list::

Show your configured integrations. Provides the ID of each integration
which can be used with the remove option.

--remove::

Remove a specific integration. Provide the ID of the integration to 
be removed.

AUTHOR
------

Ansible was originally written by Michael DeHaan. See the AUTHORS file
for a complete list of contributors.


COPYRIGHT
---------

Copyright © 2014, Michael DeHaan

Ansible is released under the terms of the GPLv3 License.


SEE ALSO
--------

*ansible*(1), *ansible-pull*(1), *ansible-doc*(1), *ansible-playbook*(1), *ansible-vault*(1)

Extensive documentation is available in the documentation site:
<http://docs.ansible.com>. IRC and mailing list info can be found
in file CONTRIBUTING.md, available in: <https://github.com/ansible/ansible>