{"id":13585746,"url":"https://github.com/openuado/niet","last_synced_at":"2025-07-12T17:32:00.734Z","repository":{"id":44566458,"uuid":"119553537","full_name":"openuado/niet","owner":"openuado","description":"Parse/Read yaml or json files directly in your shell (sh, bash, ksh, ...)","archived":false,"fork":false,"pushed_at":"2024-11-20T12:30:28.000Z","size":138,"stargazers_count":42,"open_issues_count":3,"forks_count":6,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-06-02T21:07:22.546Z","etag":null,"topics":["bash","cli","json","niet","parser","pypi","python","reader","retrieve-data","shell","yaml"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/niet/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/openuado.png","metadata":{"files":{"readme":"README.md","changelog":"ChangeLog.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":"AUTHORS","dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-01-30T15:16:25.000Z","updated_at":"2025-06-01T14:55:23.000Z","dependencies_parsed_at":"2024-06-19T00:02:52.540Z","dependency_job_id":null,"html_url":"https://github.com/openuado/niet","commit_stats":{"total_commits":96,"total_committers":6,"mean_commits":16.0,"dds":0.4375,"last_synced_commit":"d59ccf9fcb880e0f8dea1c3c888a5269d0aa82e9"},"previous_names":[],"tags_count":28,"template":false,"template_full_name":null,"purl":"pkg:github/openuado/niet","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openuado%2Fniet","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openuado%2Fniet/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openuado%2Fniet/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openuado%2Fniet/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/openuado","download_url":"https://codeload.github.com/openuado/niet/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openuado%2Fniet/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265025527,"owners_count":23699764,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bash","cli","json","niet","parser","pypi","python","reader","retrieve-data","shell","yaml"],"created_at":"2024-08-01T15:05:07.370Z","updated_at":"2025-07-12T17:32:00.396Z","avatar_url":"https://github.com/openuado.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"# niet\n\n![Build](https://github.com/openuado/niet/actions/workflows/python-app.yml/badge.svg)\n![PyPI](https://img.shields.io/pypi/v/niet.svg)\n![PyPI - Python Version](https://img.shields.io/pypi/pyversions/niet.svg)\n![PyPI - Status](https://img.shields.io/pypi/status/niet.svg)\n[![Downloads](https://pepy.tech/badge/niet)](https://pepy.tech/project/niet)\n[![Downloads](https://pepy.tech/badge/niet/month)](https://pepy.tech/project/niet/month)\n\nGet data from YAML, JSON, and TOML file directly in your shell.\n\n---\n\n\u003e How to easily parse and retrieve data from YAML file in our shell?\n\nThe previous question, few years ago, led us to the development of niet.\n\nIndeed, at that time, we needed a way to store and retrieve data for our own\nneeds. We created niet to read those data. The goal was to develop a tools\nthat will allow us to standardize how we parse YAML locally or in our CI\npipelines. We wanted something reusable and easily distribuable. Niet was born.\n\nOver the years niet evolved to introduce the support of other formats like\nTOML.\n\nNiet is like [xmllint](http://xmlsoft.org/xmllint.html) or\n[jq](https://stedolan.github.io/jq/) but for YAML, JSON and TOML data -\nyou can use it to slice and filter and map and transform structured data.\n\nYou can easily retrieve data by using simple expressions or using\nxpath advanced features to access non-trivial data.\n\nYou can easily convert YAML format into JSON, or TOML formats and vice versa.\n\nNiet is writen in Python so you can install it from a package manager (from\nPyPi) or directly by cloning this repository - no specific system rights are\nneeded to install it.\n\n## Main Features\n- Extract elements by using xpath syntax\n- Extract values from JSON, YAML, and TOML format\n- Automaticaly detect format (json/yaml)\n- Read data from a web resource\n- Read data from file or pass data from stdin\n- Format output values\n- Format output to be reused by shell `eval`\n- Convert YAML to JSON, or TOML and vice versa\n\n## Install or Update niet\n\n```sh\n$ pip install -U niet\n```\n\n## Requirements\n\n- Python 3.9 or higher\n\n## Supported versions\n\nSince niet 2.0 the support of python 2.7 have been dropped so if\nif you only have python 2.7 at hands then you can use previous version (lower\nto 2.0) but you should consider first that no support will be given on\nthese versions (no bugfix, no new feature, etc). If you report an issue or\nor propose a new feature then they will be addressed only for current or\nhigher version.\n\n## Usage\n\n### Help and options\n\n```shell\n$ niet --help\nusage: niet [-h] [-a ADDITIONAL_OBJECTS [ADDITIONAL_OBJECTS ...]] [-f {json,yaml,toml,eval,newline,ifs,squote,dquote,comma}] [-i] [-o OUTPUT_FILE] [-s] [-v] [--debug] object [file]\n\nRead data from YAML or JSON file\n\npositional arguments:\n  object                Path to object. Based on jsmespath identifiers (https://jmespath.org/specification.html#identifiers) Use '.' to get whole file. (eg: a.b.c)\n  file                  Optional JSON or YAML local filename or distant web resource at raw format. If not provided niet read from stdin\n\noptions:\n  -h, --help            show this help message and exit\n  -a ADDITIONAL_OBJECTS [ADDITIONAL_OBJECTS ...], --additional-objects ADDITIONAL_OBJECTS [ADDITIONAL_OBJECTS ...]\n                        Path to additional objects to search. Here you can pass a list of additional researchs. Allow you to combine researchs into the same command call. The researchs will be made on the original file as with the\n                        `object` parameter. Niet will output the results sequentially without delimiter between the results. If the `--output` argument is given by user, the results are appended at the end of the file sequentially. Based\n                        on jsmespath identifiers (https://jmespath.org/specification.html#identifiers) Use '.' to get whole file. (eg: a.b.c)\n  -f {json,yaml,toml,eval,newline,ifs,squote,dquote,comma}, --format {json,yaml,toml,eval,newline,ifs,squote,dquote,comma}\n                        output format\n  -i, --in-place        Perform modification in place. Will so alter read file\n  -o OUTPUT_FILE, --output OUTPUT_FILE\n                        Print output in a file instead of stdout (surcharged by in-place parameter if set)\n  -s, --silent          silent mode, doesn't display message when element was not found\n  -v, --version         print the Niet version number and exit (also --version)\n  --debug               Activate the debug mode (based on pdb)\n\noutput formats:\n  json          Return object in JSON\n  yaml          Return object in YAML\n  toml          Return object in TOML\n  eval          Return result in a string evaluable by a shell eval command as an input\n  newline       Return all elements of a list in a new line\n  ifs           Return all elements of a list separated by IFS env var\n  squote        Add single quotes to result\n  dquote        Add double quotes to result\n  comma         Return all elements separated by commas\n```\n\n### With Json from stdin\n\n```shell\n$ echo '{\"foo\": \"bar\", \"fizz\": {\"buzz\": [\"1\", \"2\", \"Fizz\", \"4\", \"Buzz\"]}}' | niet fizz.buzz\n1\n2\nFizz\n4\nBuzz\n$ echo '{\"foo\": \"bar\", \"fizz\": {\"buzz\": [\"1\", \"2\", \"Fizz\", \"4\", \"Buzz\"]}}' | niet fizz.buzz -f squote\n'1' '2''Fizz' '4' 'Buzz'\n$ echo '{\"foo\": \"bar\", \"fizz\": {\"buzz\": [\"1\", \"2\", \"fizz\", \"4\", \"buzz\"]}}' | niet . -f yaml\nfizz:\n  buzz:\n  - '1'\n  - '2'\n  - fizz\n  - '4'\n  - buzz\nfoo: bar\n$ echo '{\"foo\": \"bar\", \"fizz\": {\"buzz\": [\"zero\", \"one\", \"two\", \"three\"]}}' | niet \"fizz.buzz[2]\"\ntwo\n$ echo '{\"foo\": \"bar\", \"fizz\": {\"buzz\": [\"zero\", \"one\", \"two\", \"three\"]}}' | niet -f dquote \"fizz.buzz[0:2]\"\n\"zero\" \"one\"\n$ echo '{\"foo\": \"bar\", \"fizz\": {\"buzz\": [\"zero\", \"one\", \"two\", \"three\"]}}' | niet -f dquote \"fizz.buzz[:3]\"\n\"zero\" \"one\" \"two\"\n\n```\n\n### With YAML file\n\nConsider the yaml file with the following content:\n```yaml\n# /path/to/your/file.yaml\nproject:\n    meta:\n        name: my-project\n    foo: bar\n    list:\n        - item1\n        - item2\n        - item3\n    test-dash: value\n```\n\nYou can [download the previous example](https://gist.githubusercontent.com/4383/53e1599663b369f499aa28e27009f2cd/raw/389b82c19499b8cb84a464784e9c79aa25d3a9d3/file.yaml) locally for testing purpose or use the command line for this:\n```shell\nwget https://gist.githubusercontent.com/4383/53e1599663b369f499aa28e27009f2cd/raw/389b82c19499b8cb84a464784e9c79aa25d3a9d3/file.yaml\n```\n\nYou can retrieve data from this file by using niet like this:\n```sh\n$ niet \".project.meta.name\" /path/to/your/file.yaml\nmy-project\n$ niet \".project.foo\" /path/to/your/file.yaml\nbar\n$ niet \".project.list\" /path/to/your/file.yaml\nitem1 item2 item3\n$ # assign return value to shell variable\n$ NAME=$(niet \".project.meta.name\" /path/to/your/file.yaml)\n$ echo $NAME\nmy-project\n$ niet project.'\"test-dash\"' /path/to/your/file.json\nvalue\n```\n\n### With JSON file\n\nConsider the json file with the following content:\n```json\n{\n    \"project\": {\n        \"meta\": {\n            \"name\": \"my-project\"\n        },\n        \"foo\": \"bar\",\n        \"list\": [\n            \"item1\",\n            \"item2\",\n            \"item3\"\n        ],\n        \"test-dash\": \"value\"\n    }\n}\n```\n\nYou can [download the previous example](https://gist.githubusercontent.com/4383/1bab8973474625de738f5f6471894322/raw/0048cd2310df2d98bf4f230ffe20da8fa615cef3/file.json) locally for testing purpose or use the command line for this:\n```shell\nwget https://gist.githubusercontent.com/4383/1bab8973474625de738f5f6471894322/raw/0048cd2310df2d98bf4f230ffe20da8fa615cef3/file.json\n```\n\nYou can retrieve data from this file by using niet like this:\n```sh\n$ niet \"project.meta.name\" /path/to/your/file.json\nmy-project\n$ niet \"project.foo\" /path/to/your/file.json\nbar\n$ niet \"project.list\" /path/to/your/file.json\nitem1 item2 item3\n$ # assign return value to shell variable\n$ NAME=$(niet \"project.meta.name\" /path/to/your/file.json)\n$ echo $NAME\nmy-project\n$ niet project.'\"test-dash\"' /path/to/your/file.json\nvalue\n```\n\n### Object Identifiers\n\nAn identifier is the most basic expression and can be used to extract a single\nelement from a JSON/YAML document. The return value for an identifier is\nthe value associated with the identifier. If the identifier does not\nexist in the JSON/YAML document, than niet display a specific message and\nreturn the error code `1`, example:\n\n```sh\n$ echo '{\"foo\": \"bar\", \"fizz\": {\"buzz\": [\"1\", \"2\", \"3\"]}}' | niet fizz.gogo\nElement not found: fizz.gogo\n$ echo $?\n1\n```\n\nSee the [related section](#deal-with-errors) for more info on how to manage\nerrors with `niet`.\n\nNiet is based on `jmespath` to find results so for complexe research you can\nrefer to the [jmespath specifications](http://jmespath.org/specification.html#identifiers)\nto use identifiers properly.\n\nIf you try to search for an identifier who use some dash you need to surround\nyour research expression with simple and double quotes, examples:\n\n```sh\n$ echo '{\"foo-biz\": \"bar\", \"fizz\": {\"buzz\": [\"zero\", \"one\", \"two\", \"three\"]}}' | niet -f dquote '\"foo-biz\"'\nbar\n$ echo '{\"key-test\": \"value\"}' | niet '\"key-test\"'\nvalue\n```\n\nHowever, `niet` will detect related issues and surround automatically your\nidentifier if `jmespath` fail to handle it.\n\nHence, the following examples will return similar results than the previous\nexamples:\n\n```sh\n$ echo '{\"foo-biz\": \"bar\", \"fizz\": {\"buzz\": [\"zero\", \"one\", \"two\", \"three\"]}}' | niet -f dquote foo-biz\nbar\n$ echo '{\"key-test\": \"value\"}' | niet key-test\nvalue\n```\n\nIf your object is not at the root of your path, an example is available in\n`tests/sample/sample.json`, then you need to only surround the researched\nidentifier like this `project.'\"test-dash\"'`\n\n```json\n{\n    \"project\": {\n        \"meta\": {\n            \"name\": \"my-project\"\n        },\n        \"foo\": \"bar\",\n        \"list\": [\n            \"item1\",\n            \"item2\",\n            \"item3\"\n        ],\n        \"test-dash\": \"value\"\n    }\n}\n\n```\n\nExample:\n```sh\nniet project.'\"test-dash\"' tests/sample/sample.json\n```\n\nFurther examples with [`jmespath` identifiers](http://jmespath.org/specification.html#examples).\n\n### Additional objects\n\nAdditional objects allow you to combine more than one query.\nThe `--additional-objects` parameter accept a list of objects strings.\nThese objects are the same thing that the base object used to query\nyour inputs.\n\nThis parameter allow to generate advanced output from your input, let see an\nexample:\n\nConsider the following yaml example:\n```\nconfiguration:\n  warehouse: warehouse-name\n  database: database-name\n  object_type:\n      schema:\n        schema1: \"/path/to/schema1.sql\"\n        schema2: \"/path/to/schema2.sql\"\n```\n\nThe following command will allow us to generate an output constitued from the\nresults of the two objects used as query:\n\n```\n$ niet \".configuration.object_type | keys(@)[0]\" config.yaml\n-a \".configuration.object_type.schema.[keys(@)[0], values(@)[0]]\"\n```\n\nThe previous command will output:\n\n```\nschema\nschema1\n/path/to/schema1.sql\n```\n\nThis output wouldn't be possible without combining the result of two queries,\nthe additional objects are made for that.\n\nOutputs of these additional objects are printed sequentially in the order they\nare given in the command line.\n\n### Output\n\n#### Stdout\nBy default, niet print the output on stdout.\n\n#### Save output to a file\nIt if possible to pass a filename using -o or --output argument to writes\ndirectly in a file. This file will be created if not exists or will be\nreplaced if already exists.\n\n#### In-file modification\nIt is possible to modify directly a file using -i or --in-place argument. This will replace\nthe input file by the output of niet command. This can be used to extract some data of a file or\nreindent a file.\n\n### Output formats\nYou can change the output format using the -f or --format optional\nargument.\n\nBy default, niet detect the input format and display complex objects\nin the same format. If the object is a list or a value, newline output\nformat will be used.\n\nOutput formats are:\n  - ifs\n  - squote\n  - dquote\n  - newline\n  - yaml\n  - json\n  - toml\n\n#### ifs\nIfs output format print all values of a list or a single value in one line.\nAll values are separated by the content of IFS environment variable if defined,\nspace otherwise.\n\nExamples (consider the previous [YAML file example](#with-yaml-file)):\n```shell\n$ IFS=\"|\" niet .project.list /path/to/your/file.yaml -f ifs\nitem1|item2|item3\n$ IFS=\" \" niet .project.list /path/to/your/file.yaml -f ifs\nitem1 item2 item3\n$ IFS=\"@\" niet .project.list /path/to/your/file.yaml -f ifs\nitem1@item2@item3\n```\n\nThis is usefull in a shell for loop,\nbut your content must, of course, don't contain IFS value:\n```shell\nOIFS=\"$IFS\"\nIFS=\"|\"\nfor i in $(niet .project.list /path/to/your/file.yaml -f ifs); do\n    echo ${i}\ndone\nIFS=\"${OIFS}\"\n```\n\nPrevious example provide the following output:\n```sh\nitem1\nitem2\nitem3\n```\n\nFor single quoted see [squote](#squote) ouput or [dquote](#dquote) double quoted output with IFS\n\n#### squote\nSquotes output format print all values of a list or a single value in one line.\nAll values are quoted with single quotes and are separated by IFS value.\n\nExamples (consider the previous [YAML file example](#with-yaml-file)):\n```shell\n$ # With the default IFS\n$ niet .project.list /path/to/your/file.yaml -f squote\n'item1' 'item2' 'item3'\n$ # With a specified IFS\n$ IFS=\"|\" niet .project.list /path/to/your/file.yaml -f squote\n'item1'|'item2'|'item3'\n```\n\n#### dquote\nDquotes output format print all values of a list or a single value in one line.\nAll values are quoted with a double quotes and are separated by IFS value.\n\nExamples (consider the previous [YAML file example](#with-yaml-file)):\n```shell\n$ # With the default IFS\n$ niet .project.list /path/to/your/file.yaml -f dquote\n'item1' 'item2' 'item3'\n$ # With a specified IFS\n$ IFS=\"|\" niet .project.list /path/to/your/file.yaml -f dquote\n\"item1\"|\"item2\"|\"item3\"\n```\n\n#### newline\n\n`newline` output format print one value of a list or a single value per line.\n\nThe `newline` format is mostly usefull with shell while read loops and\nwith script interactions.\n\nExample:\n```sh\nwhile read value: do\n    echo $value\ndone \u003c $(niet --format newline project.list your-file.json)\n```\n\n#### comma\n\n`comma` output format print results on the same line and separated by commas.\n\nThe `comma` format allow you to format your outputs to consume your results\nwith other commands lines interfaces. By example some argument parser\nallow you to pass multi values for the same parameter (the\n[beagle command](https://beagle-hound.readthedocs.io/en/latest/) per\nexample allow you to\n[repeat the `--repo` option](https://beagle-hound.readthedocs.io/en/latest/cli/index.html#cmdoption-beagle-search-repo)).\n\nExample of integration with beagle and shell:\n\n```sh\n$ OSLO_PROJECTS_URL=https://raw.githubusercontent.com/openstack/governance/master/reference/projects.yaml\n$ beagle search \\\n    -f link \\\n    --repo $(niet \"oslo.deliverables.*.repos[0]\" ${OSLO_PROJECTS_URL} -f comma) 'venv'\n```\n\nThe previous command will return all the links of files\nwho contains `venv` on the openstack oslo's scope of projects (pbr,\ntaskflow, oslo.messaging, etc).\n\nElse another with a more reduced scope on openstack oslo's projects:\n\n```sh\n$ niet \"oslo.deliverables.*.repos[0][?contains(@, \\`oslo\\`) == \\`true\\`]\" \\\n    https://raw.githubusercontent.com/openstack/governance/master/reference/projects.yaml \\\n    -f comma\nopenstack/oslo-cookiecutter,openstack/oslo-specs,openstack/oslo.cache,\nopenstack/oslo.concurrency,openstack/oslo.config,openstack/oslo.context,\nopenstack/oslo.db,openstack/oslo.i18n,openstack/oslo.limit,openstack/oslo.log,\nopenstack/oslo.messaging,openstack/oslo.middleware,\nopenstack/oslo.policy,openstack/oslo.privsep,openstack/oslo.reports,\nopenstack/oslo.rootwrap,openstack/oslo.serialization,openstack/oslo.service,\nopenstack/oslo.tools,openstack/oslo.upgradecheck,openstack/oslo.utils,\nopenstack/oslo.versionedobjects,openstack/oslo.vmware,openstack/oslotest\n```\n\nIn the previous example we retrieve only the projects repos who contains\n`oslo` in their names, so other projects like `taskflow`, `pbr`, etc will\nbe ignored.\n\n#### eval\n\nEval output format allow you to eval output string to initialize shell\nvariable generated from your JSON/YAML content.\n\nYou can intialize shell variables from your entire content, example:\n\n```sh\n$ echo '{\"foo-biz\": \"bar\", \"fizz\": {\"buzz\": [\"zero\", \"one\", \"two\", \"three\"]}}' | niet -f eval .\n foo_biz=\"bar\";fizz__buzz=( zero one two three )\n$ eval $(echo '{\"foo-biz\": \"bar\", \"fizz\": {\"buzz\": [\"zero\", \"one\", \"two\", \"three\"]}}' | niet -f eval .)\n$ echo ${foo_biz}\nbar\n$ echo ${fizz__buzz}\nzero one two three\n$ eval $(echo '{\"foo-biz\": \"bar\", \"fizz\": {\"buzz\": [\"zero\", \"one\", \"two\", \"three\"]}}' | niet -f eval '\"foo-biz\"'); echo ${foo_biz}\nbar\n$ echo '{\"foo-biz\": \"bar\", \"fizz\": {\"buzz\": [\"zero\", \"one\", \"two\", \"three\"]}}' | niet -f eval fizz.buzz\nfizz_buzz=( zero one two three );\n```\n\nParent elements are separated by `__` by example the `fizz.buzz` element\nwill be represented by a variable named `fizz__buzz`. You need to consider\nthat when you call your expected variables.\n\nAlso you can initialize some shell array from your content and loop over in\na shell maner:\n\n```sh\n$ eval $(echo '{\"foo-biz\": \"bar\", \"fizz\": {\"buzz\": [\"zero\", \"one\", \"two\", \"three\"]}}' | niet -f eval fizz.buzz)\n$ for el in ${fizz_buzz}; do echo $el; done\nzero\none\ntwo\nthree\n```\n\n#### yaml\nYAML output format force output to be in YAML regardless the input file format.\n\n#### json\nJSON output format force output to be in JSON regardless the input file format.\n\n#### toml\nTOML output format force output to be in TOML regardless the input file format.\n\n### Read data from a web resource\n\nNiet allow you to read data (json/yaml/toml) from a web resource accessible by\nusing the HTTP protocole (introduced in niet 2.1).\n\nThis can be done by passing an url to niet which refer to a raw content (json,\nyaml, or toml).\n\nHere is some examples with the [openstack governance's projects data](https://github.com/openstack/governance/blob/master/reference/projects.yaml):\n\n```sh\n$ # List all the oslo projects repos (https://wiki.openstack.org/wiki/Oslo)\n$ niet \"oslo.deliverables.*.repos[0]\" \\\n    https://raw.githubusercontent.com/openstack/governance/master/reference/projects.yaml\nopenstack/automaton\nopenstack/castellan\n...\nopenstack/debtcollector\n...\nopenstack/futurist\nopenstack/oslo.cache\nopenstack/oslo.concurrency\nopenstack/oslo.config\nopenstack/oslo.context\nopenstack/oslo.db\nopenstack/oslo.i18n\nopenstack/oslo.limit\nopenstack/oslo.log\nopenstack/oslo.messaging\nopenstack/oslo.middleware\nopenstack/oslo.policy\n...\nopenstack/oslo.service\nopenstack/osprofiler\nopenstack/pbr\n...\nopenstack/stevedore\nopenstack/taskflow\nopenstack/tooz\nopenstack/whereto\n$ niet oslo.service \\\n    https://raw.githubusercontent.com/openstack/governance/master/reference/projects.yaml\nCommon libraries\n$ # Get the openstack oslo's mission\n$ niet oslo.mission \\\n    https://raw.githubusercontent.com/openstack/governance/master/reference/projects.yaml\nTo produce a set of python libraries containing code shared by OpenStack projects.\nThe APIs provided by these libraries should be high quality, stable, consistent,\ndocumented and generally applicable.\n$ eval $(niet oslo.service \\\n    https://raw.githubusercontent.com/openstack/governance/master/reference/projects.yaml -f eval) \u0026\u0026 \\\n    test \"${oslo_service}\" = \"Common libraries\"\n$ # Get the name of the oslo PTL\n$ eval $(niet oslo.ptl.name \\\n    https://raw.githubusercontent.com/openstack/governance/master/reference/projects.yaml -f eval)\n$ echo \"${oslo_ptl_name}\" # now display your evaluated result\n$ # Convert original distant yaml file into json\n$ niet . https://raw.githubusercontent.com/openstack/governance/master/reference/projects.yaml -f json\n```\n\nFor further examples of filters and selections please take a look to\n[the jmespath's doc](https://jmespath.org/examples.html).\n\n### Result not found\n\nBy default when no results was found niet display a specific message and return\nthe error code `1`, example:\n```sh\n$ echo '{\"foo\": \"bar\", \"fizz\": {\"buzz\": [\"1\", \"2\", \"3\"]}}' | niet fizz.gogo\nElement not found: fizz.gogo\n$ echo $?\n1\n```\n\nYou can avoid this behavior by passing niet into a silent mode.\n\nSilent mode allow you to hide the specific message error but continue to return\na status code equal to `1` when the key was not found.\n\nYou can use the silent mode by using the flag `-s/--silent`, example:\n```sh\n$ echo '{\"foo\": \"bar\", \"fizz\": {\"buzz\": [\"1\", \"2\", \"3\"]}}' | niet fizz.gogo -s\n$ echo $?\n1\n```\n\n### Deal with errors\n\nWhen your JSON file content are not valid niet display an error and exit\nwith return code `1`\n\nYou can easily protect your script like this:\n```sh\nPROJECT_NAME=$(niet project.meta.name your-file.yaml)\nif [ \"$?\" = \"1\" ]; then\n    echo \"Error occur ${PROJECT_NAME}\"\nelse\n    echo \"Project name: ${PROJECT_NAME}\"\nfi\n```\n\n## Examples\n\nYou can try niet by using the samples provided with the project sources code.\n\n\u003e All the following examples use the sample file available in niet sources code\nat the following location `tests/samples/sample.yaml`.\n\nSample example:\n```yaml\n# tests/samples/sample.yaml\nproject:\n    meta:\n        name: my-project\n    foo: bar\n    list:\n        - item1\n        - item2\n        - item3\n```\n\n### Extract a single value\n\nRetrieve the project name:\n```sh\n$ niet project.meta.name tests/samples/sample.yaml\nmy-project\n```\n\n### Complexe search\n\nConsider the following content:\n\n```\n$ cat /var/lib/libvirt/dnsmasq/virbr0.status\n[\n  {\n    \"ip-address\": \"192.168.122.113\",\n    \"mac-address\": \"52:54:00:91:14:02\",\n    \"hostname\": \"rhel79\",\n    \"expiry-time\": 1644251254\n  },\n  {\n    \"ip-address\": \"192.168.122.162\",\n    \"mac-address\": \"52:54:00:23:37:ed\",\n    \"hostname\": \"satellite\",\n    \"expiry-time\": 1644251837\n  }\n]\n```\n\nHere we want to retrieve the value of the ip-address field when the hostname\nis equal to `satellite`. The following command will allow you to get this\nvalue:\n\n```sh\n$ sed 's/ip/_/g' /var/lib/libvirt/dnsmasq/virbr0.status | niet \"[?hostname=='satellite'].ip\"\n192.168.122.162\n```\n\nYou should notice that first we replace `-` by `_` by using the sed\ncommand. We do that because `jmespath`, the underlying library used by `niet`\n, poorly handle key that contain `-`. We chosen to replace all - by _ to avoid\nany issues elsewhere on the file\n\nHere is an exemple of an automated ssh connection in a kvm virtualised lab\nenvironment by looking for vmname in dhcp file with `niet` and performing the\nssh connection to the server even if its ip changed.\n\nThe ssh connection here can be performed with this command:\n\n```sh\nssh -o ProxyCommand='nc $(sed 's/-/_/g' /var/lib/libvirt/dnsmasq/virbr0.status | niet \"[?hostname=='''%h'''].ip_address\") %p' root@rhel79\n```\n\nTips - to ease that use you can for example set this `.ssh/config` entry:\n\n```\nhost lab-*\nuser root\nProxyCommand /usr/bin/nc $(sed 's/-/_/g' /var/lib/libvirt/dnsmasq/virbr0.status | niet \"[?hostname=='$(echo %h | cut -d'-' -f2 )'].ip_address\") %p\n```\n\nAnd then perform a `ssh lab-rhel79` or a `ssh lab-satellite` to join all VMs\nfrom your lab, by the hostname prefixed by `lab-`.\n\n### Extract a list and parse it in shell\n\nDeal with list of items\n```sh\n$ for el in $(niet project.list tests/samples/sample.yaml); do echo ${el}; done\nitem1\nitem2\nitem3\n```\n\nAlso you can `eval` your `niet` output to setput some shell variables\nthat you can reuse in your shell scripts, the following example is similar to\nthe previous example but make use of the eval ouput format (`-f eval`):\n\n```sh\n$ eval $(niet -f eval project.list tests/samples/sample.yaml)\n$ for el in ${project__list}; do echo $el; done\nzero\none\ntwo\nthree\n```\n\n### Extract a complex object and parse it in shell\n\nExtract the object as JSON to store it in shell variable :\n```shell\n$ project=\"$(niet -f json .project tests/samples/sample.yaml)\"\n```\n\nThen parse it after in bash in this example:\n```shell\n$ niet .meta.name \u003c\u003c\u003c $project\nmy-project\n```\n\n### Transform JSON into YAML\n\nWith niet you can easily convert your JSON into YAML\n```shell\n$ niet . tests/samples/sample.json -f yaml\nproject:\n  foo: bar\n  list:\n  - item1\n  - item2\n  - item3\n  meta:\n    name: my-project\n```\n\n### Transform YAML into JSON\n\nWith niet you can easily convert your YAML into JSON\n```shell\n$ niet . tests/samples/sample.yaml -f json\n{\n    \"project\": {\n        \"meta\": {\n            \"name\": \"my-project\"\n        },\n        \"foo\": \"bar\",\n        \"list\": [\n            \"item1\",\n            \"item2\",\n            \"item3\"\n        ]\n    }\n}\n```\n\n### Transform JSON into TOML\n\nWith niet you can easily convert your JSON into TOML\n```shell\n$ niet . tests/samples/sample.json -f toml\n[project]\nfoo = \"bar\"\nlist = [\"item1\", \"item2\", \"item3\"]\ntest-dash = \"value\"\n\n[project.meta]\nname = \"my-project\"\n```\n\n### Transform YAML into TOML\n\nWith niet you can easily convert your YAML into TOML\n```shell\n$ niet . tests/samples/sample.yaml -f toml\n[project]\nfoo = \"bar\"\nlist = [\"item1\", \"item2\", \"item3\"]\ntest-dash = \"value\"\n\n[project.meta]\nname = \"my-project\"\n```\n\n### Transform TOML into YAML\n\nWith niet you can easily convert your TOML into YAML\n```shell\nniet . tests/samples/sample.toml -f yaml\nproject:\n  foo: bar\n  list:\n  - item1\n  - item2\n  - item3\n  meta:\n    name: my-project\n  test-dash: value\n```\n\n### Indent JSON file\n\nThis is an example of how to indent a JSON file :\n```shell\n$ niet . tests/samples/sample_not_indented.json\n{\n    \"project\": {\n        \"meta\": {\n            \"name\": \"my-project\"\n        },\n        \"foo\": \"bar\",\n        \"list\": [\n            \"item1\",\n            \"item2\",\n            \"item3\"\n        ],\n        \"test-dash\": \"value\"\n    }\n}\n```\n\n### Handle keys that contains dots\n\nYou may want to retrieve values from keys that contains dots, example:\n\n```yaml\n.foo:\n  something: \"a\"\n\nbar:\n  something: \"b\"\n\nfoo.z:\n  something: \"c\"\n```\n\nThen you must surround keys that contains dots with quotes, example:\n\n```\n$ niet  '\".foo\"' /tmp/test.yaml\nsomething: a\n$ niet  '\"foo.z\"' /tmp/test.yaml\nsomething: c\n```\n\n## Tips\n\nYou can pass your search with or without quotes like this:\n```sh\n$ niet project.meta.name your-file.yaml\n$ niet \"project.meta.name\" your-file.yaml\n```\n\nYou can execute `niet` step by step by using the debug mode. It will allow\nyou to inspect your execution during your debug sessions.\n\n## Contribute\n\nIf you want to contribute to niet [please first read the contribution guidelines](CONTRIBUTING.md)\n\n## Licence\n\nThis project is under the MIT License.\n\n[See the license file for more details](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenuado%2Fniet","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopenuado%2Fniet","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenuado%2Fniet/lists"}