Hammer CLI is packaged for the following RPM based distributions:
- RHEL and derivatives, version 6
- Fedora 18, 19
- Debian Wheezy, Squeezy
- Ubuntu Precise
Configuration is by default looked for in the following directories, loaded in this order:
RbConfig::CONFIG['sysconfdir']/hammer/(The actual value depends on your operatingsystem and ruby defaults.)/etc/hammer/~/.hammer/./config/(config dir in CWD)- custom location (file or directory) specified on command line -
-c CONF_FILE_PATH
In each of these directories hammer is trying to load cli_config.yml and anything in
the cli.modules.d subdirectory which is place for specific configuration of hammer modules a.k.a. plugins.
Later directories and files have precedence if they redefine the same option. Files from cli.modules.d
are loaded in alphabetical order. The modules are loaded in alphabetical order which can be overriden with explicit requirement of dependences in the modules.
The packaged version of hammer copies the template to /etc/hammer for you.
When you install from gems or source you'll have to copy config files manually.
The configuration templates are contained in the hammer_cli gem
gem contents hammer_cli|grep template.ymland can be copied to one of the locations above and changed as needed.
Hammer uses YAML formatting for its configuration.
List of existing options is available in the configuration template file with descriptions.
Plugins are disabled by default. To enable plugin create configuration file in cli.modules.d and add:enable_module: true in it.
Plugin specific configuration must be nested under plugin's name (without the hammer_cli_ prefix).
In the example we assume the gem hammer_cli_foreman with the Foreman plugin is installed. Then the plugin configuration
in ~/.hammer/cli.modules.d/foreman.yml should look as follows:
:foreman:
:enable_module: true
:host: 'https://localhost/'
:username: 'admin'
:password: 'changeme'Confirm your setup by running $ hammer -h and check that the desired commands are listed.
$ hammer -h
Usage:
hammer [OPTIONS] SUBCOMMAND [ARG] ...
Parameters:
SUBCOMMAND subcommand
[ARG] ... subcommand arguments
Subcommands:
architecture Manipulate architectures.
compute-resource Manipulate compute resources.
domain Manipulate domains.
environment Manipulate environments.
fact Search facts.
global-parameter Manipulate global parameters.
host Manipulate hosts.
hostgroup Manipulate hostgroups.
location Manipulate locations.
medium Manipulate installation media.
model Manipulate hardware models.
organization Manipulate organizations.
os Manipulate operating system.
partition-table Manipulate partition tables.
proxy Manipulate smart proxies.
puppet-class Search puppet modules.
report Browse and read reports.
sc-param Manipulate smart class parameters.
shell Interactive shell
subnet Manipulate subnets.
template Manipulate config templates.
user Manipulate users.
Options:
--autocomplete LINE Get list of possible endings
--csv Output as CSV (same as --output=csv)
--csv-separator SEPARATOR Character to separate the values
--interactive INTERACTIVE Explicitly turn interactive mode on/off
One of true/false, yes/no, 1/0.
--output ADAPTER Set output format. One of [silent, csv, base, table]
--show-ids Show ids of associated resources
--version show version
-c, --config CFG_FILE path to custom config file
-h, --help print help
-p, --password PASSWORD password to access the remote system
-u, --username USERNAME username to access the remote system
-v, --verbose be verbose
And you are done. Your hammer client is configured and ready to use.
The completion offers suggestion of possible command-line subcommands and their options as usual. It can also suggest values for options and params where file or directory path is expected.
Bash completion is automatically installed by RPM. To use it for development
setup cp ./config/hammer.completion /etc/bash_completion.d/hammer and load it
to the current shell source /etc/bash_completion.d/hammer. Make sure
the $PWD/bin is in PATH or there is full path to hammer-complete
executable specified in /etc/bash_completion.d/hammer.
Bash completion for hammer needs pre-built cache that holds description of
all subcommands and its parameters. The cache is located by default in
~/.cache/hammer_completion.yml. The location can be changed in hammer's
config file. The cache can be built manually with
hammer prebuild-bash-completion or is built automatically when completion is
used and the cache is missing (this may cause slight delay). The cache expires
if your API cache was changed (it indicates that the features on the instance
may have changed which has impact on hammer CLI options and subcommands).
Completion of values is dependent on CLI option and prameter settings, e.g.:
option '--value', 'VALUE', 'One of a, b, c', completion: { type: :enum, values: %w[a b c] }Possible options for the :completion attribute are:
{ type: :flag }option has no value, default for flags.{ type: :value }option has value of unknown type, no suggestions for the value, default.{ type: :list }option has value of list type, no suggestions for the value.{ type: :key_value_list }option has value of key=value list type, no suggestions for the value.{ type: :directory }value is directory, suggestions follow directory structure.{ type: :file, filter: '\.txt$' }value is file, suggestions follow directory structure, optional:filteris regexp to filter the results.{ type: :enum, values: ['first', 'second']}option can have one of the listed values, suggestions follow specifiedvalues.{ type: :multienum, values: ['first', 'second']}option can have one or more of the listed values, suggestions follow specifiedvalues.{ type: :schema, schema: 'a=int\,b=string' }option should have value according to specified schema, suggestion is the specified schema.
All those completion attributes are generated automatically, specify you own to override.