.TH hc 1 "2015-11-08" "version 0.1.5" "Hieracles command manual"

.SH NAME
hc \- Command tool for Hieracles
.SH SYNOPSIS
.B hc 
.I fqdn
.I action
.B [
.I options
.B ]

.SH DESCRIPTION
.PP
Hieracles is a command-line tool for analysis and deep examination
of [Hiera][hiera] parameters in a [Puppet][puppet] setup. It's used
internally at Gandi and its first incarnation is strongly
tied to Gandi puppet architecture. But Hieracles tends to become, in
time, a generic Hiera overlay visualization tool.
.PP
hc command takes at minimum 2 arguments:
.RS 4
.IP fqdn 10
the fqdn under which the node is known in the ENC dir
.IP action 
the action needs to be one of the following
.RS
.IP info 10
provides the farm, datacenter, country associated to the given fqdn.
.IP files
list all files containing params affecting this fqdn 
(in more than commons).
.IP paths
list all file paths for files with params.
.IP modules
list modules included in the farm where the node is.
.IP params
list params for the node matching the fqdn.
An extra filter string can be added to limit the list
use ruby regexp without the enclosing slashes
.RS
eg. hc <fqdn> params postfix.*version
.RE
.RS
eg. hc <fqdn> params '^postfix'
.RE
.RS
eg. hc <fqdn> params 'version$'
.RE
.IP all
same as params but including the common.yaml params (huge)
Also accepts a search string
.RE
.RE

.SH OPTIONS

.TP
.PD 0
.B \-v
.TP
.PD
.B \-\-version
outputs version.

.TP
.PD 0
.B \-f \fRformat
.TP
.PD
.B \-\-format \fRformat
outputs in the selected format. Available formats are
csv, json, console, plain, yaml and rawyaml
.IP
Note that the difference between yaml and rawyaml 
is that rawyaml don't include comments with the 
provenance of each params.

.TP
.PD 0
.B \-p \fRextraparam=what;anotherparam=this
.TP
.PD
.B \-\-params \fRextraparam=what;anotherparam=this
makes possible to add additional params. 
Those params will be merged with the ones provided in the hierafile.

.TP
.PD 0
.B \-c \fRfile
.TP
.PD
.B \-\-config \fRfile
specify an alternative config file instead of 
~/.config/hieracles/config.yaml

.TP
.PD 0
.B \-h \fRfile
.TP
.PD
.B \-\-hierafile \fRfile
specify an alternative hierafile instead of the one 
stated in the configfile.

.TP
.PD 0
.B \-b \fRpath
.TP
.PD
.B \-\-basepath \fRpath
the basepath is prepended to the paths found in the configfile and the hierafile. Default is ./ but you can change this using the -b option.

.TP
.PD 0
.B \-e \fRpath
.TP
.PD
.B \-\-encdir \fRpath
encdir is where we can find the ENC definitions. It's stated in the configfile but can be overridden by the -e option.


.TP
.PD 0
.B \-y \fRfile
.TP
.PD
.B \-\-yaml \fRfile
use an arbitrary facts file that can be obtained with
.B "facter -y"
on the given node. This is useful for having a set of default fact
and test locally what would be the consequences of switching from 
one environment to another. It's also good for anticipation
of how new node, that don't have facts yet, will behave.


.TP
.PD 0
.B \-j \fRfile
.TP
.PD
.B \-\-json \fRfile
same as the 
.B "-y"
flag but in json format, which can be obtained on the node with 
.B "facter -j"
and this behave the same way. Note that the \-y has precedence on
the \-j in this context.


.TP
.PD 0
.B \-i
.TP
.PD
.B \-\-interactive
if a scope var is not defined or if the file declared in hiera config is not found, this entry is silently ignored.
.RS
This option enables the 
.B "interactive mode"
in which you are prompted to fill up for undefined scope variables encountered in the hiera config file. This behavior can be made systematic by enabling 
.I "interactive: true"
in hieracles configuration file.
.RE

.SH FILES
.I ~/.config/hieracles/config.yaml
.RS
Where sits the main hieracles configuration

.SH EXAMPLES
A typical config file would look like:
.PP
.RS
---
.RE
.RS
classpath: farm_modules/%s/manifests/init.pp
.RE
.RS
hierafile: dev/hiera-local.yaml
.RE
.RS
encpath: enc
.RE
.RS
interactive: false
.RE

.SH SEE ALSO
hiera(1), puppet(8)

.SH BUGS
Please report any bug to https://github.com/Gandi/hieracles/issues

.SH AUTHORS
Copyright (c) 2015 gandi.net https://gandi.net
.LP
Hieracles is written by mose@gandi.net
.LP
https://github.com/Gandi/hieracles