Installation¶ ↑
Hammer CLI is packaged for the following RPM based distributions:
-
RHEL and derivatives, version 6
-
Fedora 18, 19
-
Debian Wheezy, Squeezy
-
Ubuntu Precise
Select your way of installation¶ ↑
Configuration¶ ↑
Locations¶ ↑
Configuration is by default looked for in the following directories, loaded in this order:
-
['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.
Manual installation¶ ↑
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
bash gem contents hammer_cli|grep template.yml
and can be
copied to one of the locations above and changed as needed.
Tuning options¶ ↑
Hammer uses YAML formatting for its configuration.
List of existing options is available in the configuration template file with descriptions.
Plugins¶ ↑
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'
Use the hammer¶ ↑
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.
Autocompletion¶ ↑
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).
Available value types¶ ↑
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 :filter
is regexp to filter the results.
- { type: :enum, values: ['first', 'second']}
option can have one of the listed values, suggestions follow specified
values
. - { type: :multienum, values: ['first',
'second']}
option can have one or more of the listed values,
suggestions follow specified values
. - { 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.