onyo get

Return values of the requested KEYs for matching assets.

If no KEYs are given, the path and all keys in the asset name are printed (see onyo.assets.name-format). If no PATHs are given, the current working directory is used.

All keys, both on-disk YAML and PSEUDO-KEYS, can be queried, matched, and sorted. Dictionary subkeys are addressed using a period (e.g. model.name).

  • onyo.is.asset: is an asset

  • onyo.is.directory: is a directory

  • onyo.is.template: is a template

  • onyo.path.absolute: absolute path of the item

  • onyo.path.name: name of the item

  • onyo.path.parent (default alias: directory): parent directory of the item relative to repo root

  • onyo.path.relative (default alias: path): path of the item relative to repo root

By default, the results are sorted by onyo.path.relative.

usage: onyo get [-h] [-d DEPTH] [-k KEY [KEY ...]] [-H] [-M MATCH [MATCH ...]]
                [-i INCLUDE [INCLUDE ...]] [-x EXCLUDE [EXCLUDE ...]]
                [-s SORT_KEY [SORT_KEY ...]] [-S SORT_KEY [SORT_KEY ...]]
                [-t TYPES [TYPES ...]]

Named Arguments

-d, --depth

Number of levels to descend into the directories specified by include. A depth of 0 descends recursively without limit. Default is 0.

Default: 0

-k, --keys

**KEY**s to print the values of. Default is asset-name keys and path.

-H, --machine-readable

Print results in a machine-friendly format (no headers; separate values with a single tab) rather than a human-friendly format (headers and padded whitespace to align columns).

Default: False

-M, --match

Criteria to match in the form KEY=VALUE — where VALUE is a literal string or a python regular expression. Valid operators are =, !=, >, >=, <, and <=. All keys can be matched, and are not limited to those specified by --keys.

Tags supported are:

  • <bool>: a boolean

  • <dict>: a dictionary

  • <empty>: null or an empty string, dictionary, or list

  • <false>: false, False or FALSE

  • <list>: a list

  • <null>: null, Null, NULL, ~, or nothing

  • <true>: true, True, or TRUE

  • <unset>: the key does not exist

Tags and regular expressions work only with = and !=.

An item must meet the criteria of all match statements for it to be printed (i.e. each statement is connected with a logical and).

When --match is invoked multiple times, an item must meet the criteria of only one invocation for it to be printed (i.e. each invocation is connected with a logical or).

For example

--match type=laptop make=apple --match type=display make=eizo

results logically to

(type=laptop and make=apple) or (type=display and make=eizo)

-i, --include

Paths under which to query. Default is inventory root.

-x, --exclude

Paths to exclude (i.e. results underneath will not be returned).

-s, --sort-ascending

Sort matches by SORT-KEY in ascending order. Multiple **SORT-KEY**s will be sorted in the order given. This can be intermixed with -s/--sort-descending. All keys can be sorted, and are not limited to those specified by --keys.

-S, --sort-descending

Sort matches by SORT-KEY in descending order. Multiple **SORT-KEY**s will be sorted in the order given. This can be intermixed with -s/--sort-ascending. All keys can be sorted, and are not limited to those specified by --keys.

-t, --types

Possible choices: assets, directories

Item types to query. Equivalent to onyo.is.asset=True and onyo.is.directory=True. Default is assets.

Default: ['assets']

Exit Status

The exit status is 0 if at least one result is found, 1 if there are no results, and 2 if an error occurred.

These exit values match those of grep.

Examples

List all assets belonging to a user:

$ onyo get --include accounting/Bingo\ Bob

List all laptops in the warehouse:

$ onyo get --match type=laptop --include warehouse/

Get the path of all laptops of a specific make and model, and print in machine parsable format (suitable for piping):

$ onyo get --match type=laptop make=apple model=macbookpro --keys path --machine-readable