augtool [\s-1OPTIONS\s0] [\s-1COMMAND\s0]


Augeas is a configuration editing tool. It parses configuration files in their native formats and transforms them into a tree. Configuration changes are made by manipulating this tree and saving it back into native config files.

augtool provides a command line interface to the generated tree. \s-1COMMAND\s0 can be a single command as described under \*(L"\s-1COMMANDS\s0\*(R". When called with no \s-1COMMAND\s0, it reads commands from standard input until an end-of-file is encountered.


-c, --typecheck

Typecheck lenses. This can be very slow, and is therefore not done by default, but is highly recommended during development.

-b, --backup

When files are changed, preserve the originals in a file with extension '.augsave'

-n, --new

Save changes in files with extension '.augnew', do not modify the original files

-r, --root=\s-1ROOT\s0

Use directory \s-1ROOT\s0 as the root of the filesystem. Takes precedence over a root set with the \s-1AUGEAS_ROOT\s0 environment variable.

-I, --include=\s-1DIR\s0

Add \s-1DIR\s0 to the module loadpath. Can be given multiple times. The directories set here are searched before any directories specified in the \s-1AUGEAS_LENS_LIB\s0 environment variable, and before the default directories /usr/share/augeas/lenses and /usr/share/augeas/lenses/dist.

-t, --transform=\s-1XFM\s0

Add a file transform; uses the 'transform' command syntax, e.g. \*(C`-t 'Fstab incl /etc/fstab.bak'\*(C'.

-f, --file=\s-1FILE\s0

Read commands from \s-1FILE\s0.

-i, --interactive

Read commands from the terminal. When combined with -f or redirection of stdin, drop into an interactive session after executing the commands from the file.

-e, --echo

When reading commands from a file via stdin, echo the commands before printing their output.

-s, --autosave

Automatically save all changes at the end of the session.

-S, --nostdinc

Do not search any of the default directories for modules. When this option is set, only directories specified explicitly with -I or specified in \s-1AUGEAS_LENS_LIB\s0 will be searched for modules.

-L, --noload

Do not load any files on startup. This is generally used to fine-tune which files to load by modifying the entries in \*(C`/augeas/load\*(C' and then issuing a \*(C`load\*(C' command.

-A, --noautoload

Do not load any lens modules, and therefore no files, on startup. This creates no entries under \*(C`/augeas/load\*(C' whatsoever; to read any files, they need to be set up manually and loading must be initiated with a \*(C`load\*(C' command. Using this option gives the fastest startup.


Print version information and exit. The version is also in the tree under \*(C`/augeas/version\*(C'.


In interactive mode, commands and paths can be completed by pressing \*(C`TAB\*(C'.

The paths accepted as arguments by commands use a small subset of XPath path expressions. A path expression consists of a number of segments, separated by \*(C`/\*(C'. In each segment, the character \*(C`*\*(C' can be used to match every node regardless of its label. Sibling nodes with identical labels can be distinguished by appending \*(C`[N]\*(C' to their label to match the N-th sibling with such a label. The last sibling with a specific label can be reached as \*(C`[last()]\*(C'. See \*(L"\s-1EXAMPLES\s0\*(R" for some examples of this.


Exit the program

ls <\s-1PATH\s0>

List the direct children of \s-1PATH\s0

match <\s-1PATTERN\s0> [<\s-1VALUE\s0>]

Find all paths that match \s-1PATTERN\s0. If \s-1VALUE\s0 is given, only the matching paths whose value equals \s-1VALUE\s0 are printed

rm <\s-1PATH\s0>

Delete \s-1PATH\s0 and all its children from the tree

mv <\s-1SRC\s0> <\s-1DST\s0>

Move node \s-1SRC\s0 to \s-1DST\s0. \s-1SRC\s0 must match exactly one node in the tree. \s-1DST\s0 must either match exactly one node in the tree, or may not exist yet. If \s-1DST\s0 exists already, it and all its descendants are deleted. If \s-1DST\s0 does not exist yet, it and all its missing ancestors are created.

set <\s-1PATH\s0> <\s-1VALUE\s0>

Associate \s-1VALUE\s0 with \s-1PATH\s0. If \s-1PATH\s0 is not in the tree yet, it and all its ancestors will be created.

clear <\s-1PATH\s0>

Set the value for \s-1PATH\s0 to \s-1NULL\s0. If \s-1PATH\s0 is not in the tree yet, it and all its ancestors will be created.

setm <\s-1BASE\s0> <\s-1SUB\s0> <\s-1VALUE\s0>

Set multiple nodes in one operation. Find or create a node matching \s-1SUB\s0 by interpreting \s-1SUB\s0 as a path expression relative to each node matching \s-1BASE\s0. If \s-1SUB\s0 is '.', the nodes matching \s-1BASE\s0 will be modified.

get <\s-1PATH\s0>

Print the value associated with \s-1PATH\s0

print [<\s-1PATH\s0>]

Print entries in the tree. If \s-1PATH\s0 is given, printing starts there, otherwise the whole tree is printed

dump-xml [<\s-1PATH\s0>] [<\s-1FILENAME\s0>]

Print entries in the tree as \s-1XML\s0. If \s-1PATH\s0 is given, printing starts there, otherwise the whole tree is printed. If \s-1FILENAME\s0 is given, the \s-1XML\s0 is saved to the given file.

ins <\s-1LABEL\s0> <\s-1WHERE\s0> <\s-1PATH\s0>

Insert a new node with label \s-1LABEL\s0 right before or after \s-1PATH\s0 into the tree. \s-1WHERE\s0 must be either 'before' or 'after'.


Save all pending changes to disk. Unless either the -b or -n command line options are given, files are changed in place.


Load files according to the transforms in \*(C`/augeas/load\*(C'.

defvar <\s-1NAME\s0> <\s-1EXPR\s0>

Define the variable \s-1NAME\s0 to the result of evaluating \s-1EXPR\s0. The variable can be used in path expressions as $NAME. Note that \s-1EXPR\s0 is evaluated when the variable is defined, not when it is used.

defnode <\s-1NAME\s0> <\s-1EXPR\s0> [<\s-1VALUE\s0>]

Define the variable \s-1NAME\s0 to the result of evaluating \s-1EXPR\s0, which must be a nodeset. If no node matching \s-1EXPR\s0 exists yet, one is created and \s-1NAME\s0 will refer to it. If \s-1VALUE\s0 is given, this is the same as 'set \s-1EXPR\s0 \s-1VALUE\s0'; if \s-1VALUE\s0 is not given, the node is created as if with 'clear \s-1EXPR\s0' would and \s-1NAME\s0 refers to that node.

span <\s-1PATH\s0>

Print the name of the file from which the node \s-1PATH\s0 was generated, as well as information about the positions in the file corresponding to the label, the value, and the entire node. \s-1PATH\s0 must match exactly one node. You need to run 'set /augeas/span enable' prior to loading files to enable recording of span information. It is disabled by default.


Print this help text



The file system root, defaults to '/'. Can be overridden with the -r command line option


Colon separated list of directories with lenses. Directories specified here are searched after any directories set with the -I command line option, but before the default directories /usr/share/augeas/lenses and /usr/share/augeas/lenses/dist


Normally, exit status is 0. If one or more commands fail, the exit status is set to a non-zero value.

Note though that failure to load some of the files specified by transforms in \*(C`/augeas/load\*(C' is not considered a failure. If it is important to know that all files were loaded, you need to issue a \*(C`match /augeas//error\*(C' after loading to find out details about what files could not be loaded and why.


  # command line mode
  augtool print /files/etc/hosts/

  # interactive mode
  augtool> help
  augtool> print /files/etc/hosts/

  # Print the third entry from the second AcceptEnv line
  augtool print '/files/etc/ssh/sshd_config/AcceptEnv[2]/3'

  # Find the entry in inittab with action 'initdefault'
  augtool> match /files/etc/inittab/*/action initdefault

  # Print the last alias for each entry in /etc/hosts
  augtool> print /files/etc/hosts/*/alias[last()]


Lenses and schema definitions in /usr/share/augeas/lenses and /usr/share/augeas/lenses/dist


David Lutterkort <[email protected]>


Copyright 2007-2012 Red Hat Inc.

Augeas (and augtool) are distributed under the \s-1GNU\s0 Lesser General Public License (\s-1LGPL\s0)

RELATED TO augtool…

Augeas project homepage <>