{"id":13414685,"url":"https://github.com/jmespath/jp","last_synced_at":"2025-06-18T15:43:02.236Z","repository":{"id":36151818,"uuid":"40455851","full_name":"jmespath/jp","owner":"jmespath","description":"Command line interface to JMESPath - http://jmespath.org","archived":false,"fork":false,"pushed_at":"2023-06-15T20:34:07.000Z","size":155,"stargazers_count":756,"open_issues_count":17,"forks_count":48,"subscribers_count":20,"default_branch":"master","last_synced_at":"2025-03-05T16:13:48.710Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jmespath.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2015-08-10T00:45:26.000Z","updated_at":"2025-02-26T19:08:43.000Z","dependencies_parsed_at":"2024-01-07T21:19:43.194Z","dependency_job_id":null,"html_url":"https://github.com/jmespath/jp","commit_stats":null,"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jmespath%2Fjp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jmespath%2Fjp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jmespath%2Fjp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jmespath%2Fjp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jmespath","download_url":"https://codeload.github.com/jmespath/jp/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243658055,"owners_count":20326459,"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":[],"created_at":"2024-07-30T21:00:32.860Z","updated_at":"2025-03-14T22:32:01.702Z","avatar_url":"https://github.com/jmespath.png","language":"Python","funding_links":[],"categories":["Python","others","json","\u003ca name=\"data-management-json\"\u003e\u003c/a\u003eData management - JSON/YAML/etc."],"sub_categories":[],"readme":"jp\n==\n\nThe ``jp`` command is a command line interface to\n[JMESPath](http://jmespath.org), an expression\nlanguage for manipulating JSON:\n\n```\n$ echo '{\"foo\": {\"bar\": [\"a\", \"b\", \"c\"]}}' | jp foo.bar[1]\n\"b\"\n```\n\n\n# Installing\n\nIf you're a Mac user, you can install via homebrew from the JMESPath\nHomebrew tap:\n\n```sh\nbrew install jmespath/jmespath/jp\n```\n\nIf you're a Windows user, you can install via [Scoop](http://scoop.sh/):\n\n```Batchfile\nscoop install jp\n```\n\nYou can download prebuilt binaries if you prefer.\nCheck the [Release page](https://github.com/jmespath/jp/releases)\n to download the latest ``jp`` executable.  There are binaries\navailable for Windows, Linux, Mac, FreeBSD.\n\nFor example, to install the latest version on a 64 bit Linux environment use:\n\n```sh\nsudo wget https://github.com/jmespath/jp/releases/latest/download/jp-linux-amd64 \\\n  -O /usr/local/bin/jp  \u0026\u0026 sudo chmod +x /usr/local/bin/jp\n```\n\n## Building from Source\n\nIf you have a Go environment installed you can also run:\n``go install github.com/jmespath/jp@latest`` to get the latest version\nof jmespath.  If you have the repo checked out locally you can also\njust ``go build`` the project:\n\n```sh\ngit clone https://github.com/jmespath/jp.git\ncd jp\ngo build\n./jp --help\n```\n\nAnd finally, if you have a go environment setup, but don't\nhave a workspace/GOPATH configured, you can just run\n``scripts/build-self-contained`` and it will build the\n``jp`` executable for you:\n\n```sh\ngit clone https://github.com/jmespath/jp.git\ncd jp\nscripts/build-self-contained\n./jp --help\n```\n\n## Cross platform binaries\n\nIf you have a go 1.5 environment setup, you can build cross platform binaries\nby running ``scripts/build-all-platforms``.\nThis will put executables in the ``build/`` directory and each\nexecutable will be named ``jp-\u003cplatform\u003e``, e.g\n``jp-darwin-amd64``,  ``jp-linux-386``, etc.\n\n\n# Usage\n\nThe most basic usage of ``jp`` is to accept input JSON data through stdin,\napply the JMESPath expression you've provided as an argument to ``jp``, and\nprint the resulting JSON data to stdout.\n\n```\n$ echo '{\"key\": \"value\"}' | jp key\n\"value\"\n\n$ echo '{\"foo\": {\"bar\": [\"a\", \"b\", \"c\"]}}' | jp foo.bar[1]\n\"b\"\n```\n\nNote the argument after ``jp``.  This is a JMESPath expression.\nIf you have no idea what that is, there's a\n[JMESPath Tutorial](http://jmespath.org/tutorial.html) that\nwill take you through the JMESPath language.\n\n## Input From a File\n\nIn addition to this basic usage, there's also other ways to use\n``jp``.  First, instead of reading from stdin, you can provide\na JSON file as input using the ``-f/--filename`` option:\n\n\n```\n$ echo '{\"foo\": {\"bar\": \"baz\"}}' \u003e /tmp/input.json\n$ jp -f /tmp/input.json foo.bar\n\"baz\"\n```\n\n## Unquoted Output\n\n[[Notice]] the output of the above command is ``\"baz\"``, that is,\na double quote ``\"``, followed by baz, followed by another\na final double quote.  This can be problematic if you're\ntrying to use this with other commands that just want\nthe string and *not* the quoted string.  For example:\n\n\n```sh\ncurl -s https://api.github.com/repos/golang/go/events | jp [0].actor.url\n\"https://api.github.com/users/robpike\"\n```\n\nNow let's suppose we want to then curl the above URL.  Our first\nattempt might look something like this:\n\n```sh\ncurl $(curl -s https://api.github.com/repos/golang/go/events | ./jp [0].actor.url)\n```\n\nAnd it would fail with:\n\n```\ncurl: (1) Protocol \"https not supported or disabled in libcurl\n```\n\nTo fix this, we can use the ``-u/--unquoted`` option to specify that\nany result that is a string will be printed without quotes.  Note\nthat the result is not surrounded by double quotes:\n\n```sh\ncurl -s https://api.github.com/repos/golang/go/events | jp --unquoted [0].actor.url\nhttps://api.github.com/users/robpike\n```\n\nIf this is a common enough occurance for you, you can set the ``JP_UNQUOTED`` environment\nvariable to make this the default behavior:\n\n```sh\nexport JP_UNQUOTED=true\ncurl -s https://api.github.com/repos/golang/go/events | jp --unquoted [0].actor.url\nhttps://api.github.com/users/robpike\n```\n\n\nAlso keep in mind that this behavior\nonly applies if the result of evaluating the JMESPath expression is a string:\n\n```\n$ echo '{\"foo\": [\"bar\", \"baz\"]}' | jp -u foo[0]\nbar\n# But -u does nothing here because the result is an array, not a string:\n$ echo '{\"foo\": [\"bar\", \"baz\"]}' | jp -u foo\n[\n  \"bar\",\n  \"baz\"\n]\n```\n\nYou can also use the ``-u/--unquoted`` option along with the\n[join](http://jmespath.org/specification.html#join) function to create a list\nof strings that can be piped into other POSIX text tools. For example:\n\n```\n$ echo '{\"foo\": {\"bar\": [\"a\", \"b\", \"c\"]}}' | jp foo.bar\n[\n  \"a\",\n  \"b\",\n  \"c\"\n]\n```\n\nSuppose we want to iterate over the 3 values in the list and\nrun some bash code for each value.  We can do this by running:\n\n```\n$ for name in $(echo '{\"foo\": {\"bar\": [\"a\", \"b\", \"c\"]}}' | \\\n  jp -u 'join(`\"\\n\"`, foo.bar)');\n  do\n      echo \"Processing: $name\";\n  done\nProcessing: a\nProcessing: b\nProcessing: c\n```\n\n\n## Examples\n\nIf you're new to the JMESPath language, or just want to see what the language is\ncapable of, you can check out the [JMESPath tutorial](http://jmespath.org/tutorial.html)\nas well as the [JMESPath examples](http://jmespath.org/examples.html), which contains\na curated set of JMESPath examples.  But for now, here's a real world example.\nLet's say you wanted to see what the latest activity was with regard to the issue\ntracker for one of your github issues.  Here's a simple way to do this:\n\n```\n$ curl -s https://api.github.com/repos/golang/go/events | jp \\\n\"[?type=='IssuesEvent'].payload.\\\n{Title: issue.title, URL: issue.url, User: issue.user.login, Event: action}\"\n\n[\n  {\n    \"Event\": \"opened\",\n    \"Title\": \"release: cherry pick changes for 1.5 to release branch\",\n    \"URL\": \"https://api.github.com/repos/golang/go/issues/12093\",\n    \"User\": \"adg\"\n  },\n  {\n    \"Event\": \"closed\",\n    \"Title\": \"fmt: x format verb for []byte fails in a recursive call to Fscanf from a scanln call in go1.5rc1\",\n    \"URL\": \"https://api.github.com/repos/golang/go/issues/12090\",\n    \"User\": \"hubslave\"\n  },\n  {\n    \"Event\": \"closed\",\n    \"Title\": \"doc: release notes recommend wrong version of NaCl\",\n    \"URL\": \"https://api.github.com/repos/golang/go/issues/12062\",\n    \"User\": \"davecheney\"\n  },\n  {\n    \"Event\": \"opened\",\n    \"Title\": \"cmd/godoc: show internal packages when explicitly requested\",\n    \"URL\": \"https://api.github.com/repos/golang/go/issues/12092\",\n    \"User\": \"jacobsa\"\n  }\n]\n```\n\nTry it for your own repo, instead of ``/golang/go``, replace it with your own\n``/owner/repo`` value.  In words, this expression says:\n\n* For each element in the top level list, select only the elements where the\n``type`` key is equal to the string ``IssueEvent``\n* For each of those filtered elements select the ``payload`` hash.\n* Each each ``payload`` hash, we're going to create our own hash that has\n4 keys: ``Title``, ``URL``, ``User``, ``Event``.  The value for each of key\nis the result of evaluating these expressions in their respective order:\n``issue.title``, ``issue.url``, ``issue.user.login``, ``action``.\n\nEnsure that if your expression has spaces you surround the expression\nin quotes, as shown in the example above.\n\n## Testing\n\nThe parsing and evaluation of JMESPath expression is done in the\ngo-jmespath library, which is a dependency of this project.  ``go-jmespath``\nhas extensive testing to ensure it is parsing and evaluating JMESPath\nexpressions correctly.\n\nTo ensure that there are no regressions between `go-jmespath` and `jp`,\nthe entire suite of [JMESPath compliance tests](https://github.com/jmespath/jmespath.test)\nare run against the `jp` executable.\n\nThis repo also include CLI specific test that verify the command line\noptions and output work as intended.\n\nYou can run all of these tests for `jp` by running `make test`:\n\n```\n$ make test\n# CLI specific test cases.\ntest/vendor/bats/libexec/bats test/cases\n ✓ Has valid help output\n ✓ Can display version\n ✓ Can search basic expression\n ✓ Can search subexpr expression\n ✓ Can read input from file\n ✓ Can print result unquoted\n ✓ Bad JMESPath expression has non zero rc\n - Large numbers are not printed with scientific notation (skipped)\n ✓ Can accept expression from file\n ✓ Can pretty print expr AST\n ✓ Can sort int array\n\nX tests, 0 failures, 1 skipped\n# JMESPath compliance tests, using the jp-compliance\n# runner from github.com/jmespath/jmespath.test\ntest/jp-compliance -d test/compliance/ -e ./jp\n............................................................\n............................................................\n............................................................\n............................................................\n............................................................\n............................................................\n............................................................\n............................................................\nOK\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjmespath%2Fjp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjmespath%2Fjp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjmespath%2Fjp/lists"}