{"id":13448475,"url":"https://github.com/micha/resty","last_synced_at":"2025-05-15T05:07:47.399Z","repository":{"id":571702,"uuid":"203438","full_name":"micha/resty","owner":"micha","description":"Little command line REST client that you can use in pipelines (bash or zsh).","archived":false,"fork":false,"pushed_at":"2023-02-17T16:10:52.000Z","size":254,"stargazers_count":2651,"open_issues_count":18,"forks_count":142,"subscribers_count":67,"default_branch":"master","last_synced_at":"2025-04-14T08:11:33.351Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Shell","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/micha.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"MIT-LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2009-05-17T22:48:44.000Z","updated_at":"2025-04-12T04:48:00.000Z","dependencies_parsed_at":"2023-07-05T15:01:22.429Z","dependency_job_id":null,"html_url":"https://github.com/micha/resty","commit_stats":{"total_commits":377,"total_committers":17,"mean_commits":"22.176470588235293","dds":0.5358090185676392,"last_synced_commit":"cefdcb1f6d15b0d6af037b53fc3feab2f3a56184"},"previous_names":[],"tags_count":18,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/micha%2Fresty","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/micha%2Fresty/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/micha%2Fresty/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/micha%2Fresty/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/micha","download_url":"https://codeload.github.com/micha/resty/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254276447,"owners_count":22043867,"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-31T05:01:46.695Z","updated_at":"2025-05-15T05:07:42.388Z","avatar_url":"https://github.com/micha.png","language":"Shell","readme":"Resty\n=====\n\n[![GitHub release](https://img.shields.io/github/release/micha/resty.svg)](https://github.com/micha/resty/releases)\n[![Build Status](https://travis-ci.org/AdrieanKhisbe/resty.svg?branch=master)](https://travis-ci.org/AdrieanKhisbe/resty)\n[![GitHub license](https://img.shields.io/github/license/micha/resty.svg)](https://github.com/micha/resty/blob/master/MIT-LICENSE.txt)\n\n\u003e **Resty** is a *tiny* script wrapper for [curl](http://curl.haxx.se/).\n\nIt provides a simple, concise shell interface for interacting with\n[REST](http://en.wikipedia.org/wiki/Representational_State_Transfer) services.\nSince it is implemented as functions in your shell and not in its own separate\ncommand environment you have access to all the powerful shell tools, such\nas `perl`, `awk`, `grep`, `sed`, etc. You can use resty in pipelines to process data\nfrom `REST` services, and `PUT`, `PATCH`, or `POST` the data right back.  You can even pipe\nthe data in and then edit it interactively in your text editor prior to `PUT`,\n`PATCH`, or `POST`.\n\nCookies are supported automatically and stored in a file locally. Most of\nthe arguments are remembered from one call to the next to save typing. It\nhas pretty good defaults for most purposes. Additionally, **resty** allows you\nto easily provide your own options to be passed directly to `curl`, so even\nthe most complex requests can be accomplished with the minimum amount of\ncommand line pain.\n\n[Here is a nice screencast showing resty in action](http://jpmens.net/2010/04/26/resty/) (by Jan-Piet Mens).\n\n## Quick Start\n\nYou have `curl`, right? Okay.\n\n      $ curl -L https://raw.githubusercontent.com/micha/resty/master/resty \u003e resty\n\nSource the script before using it.\n\n      $ . resty\n\nOnce **resty** is installed, set your REST host to which you will be making your requests.\n\n      $ resty http://127.0.0.1:8080/data\n      http://127.0.0.1:8080/data*\n\nAnd now you can Make some HTTP requests.\n\n      $ GET /blogs.json\n      [ {\"id\" : 1, \"title\" : \"first post\", \"body\" : \"This is the first post\"}, ... ]\n\n      $ PUT /blogs/2.json '{\"id\" : 2, \"title\" : \"updated post\", \"body\" : \"This is the new.\"}'\n      {\"id\" : 2, \"title\" : \"updated post\", \"body\" : \"This is the new.\"}\n\n      $ DELETE /blogs/2\n\n      $ POST /blogs.json '{\"title\" : \"new post\", \"body\" : \"This is the new new.\"}'\n      {\"id\" : 204, \"title\" : \"new post\", \"body\" : \"This is the new new.\"}\n\n## Installation\n\nThere are several way to install **resty** other than `curl`ing it and sourcing it.\n\nHere are some shell package manager that are supported:\n\n- **Bpkg** : with [`bpkg`](http://www.bpkg.sh/) installed just run `bpkg install -g micha/resty`,\n   then follow the instruction by adding `source ~/.bashrc.d/resty` to your `bashrc`\n- **Antigen** : with [`antigen`](https://github.com/zsh-users/antigen) for zsh, just add `antigen bundle micha/resty` in your `.zshrc`\n- **Zplug**: with [`zplug`](https://github.com/zplug/zplug) installed, just add `zplug micha/resty, use:'resty'` in your `.zshrc`\n- **Oh my Zsh**: clone the github repositery in the `plugins` directory of `ZSH_CUSTOM` and add `resty` to you `plugins` list\n\n\n## Usage\n\n      source resty [-W] [remote] [OPTIONS]    # load functions into shell\n      resty [-v]                              # prints current request URI base\n      resty \u003cremote\u003e [OPTIONS]                # sets the base request URI\n\n      HEAD [path] [OPTIONS]                   # HEAD request\n      OPTIONS [path] [OPTIONS]                # OPTIONS request\n      GET [path] [OPTIONS]                    # GET request\n      DELETE [path] [OPTIONS]                 # DELETE request\n      PUT [path] [data] [OPTIONS]             # PUT request\n      PATCH [path] [data] [OPTIONS]           # PATCH request\n      POST [path] [data] [OPTIONS]            # POST request\n      TRACE [path] [OPTIONS]                  # TRACE request\n\n      Options:\n\n      -Q            Don't URL encode the path.\n      -q \u003cquery\u003e    Send query string with the path. A '?' is prepended to\n                    \u003cquery\u003e and concatenated onto the \u003cpath\u003e.\n      -W            Don't write to history file (only when sourcing script).\n      -V            Edit the input data interactively in 'vi'. (PUT, PATCH,\n                    and POST requests only, with data piped to stdin.)\n      -Z            Raw output. This disables any processing of HTML in the\n                    response.\n      -v            Verbose output. When used with the resty command itself\n                    this prints the saved curl options along with the current\n                    URI base. Otherwise this is passed to curl for verbose\n                    curl output.\n      --dry-run     Just output the curl command.\n      \u003ccurl opt\u003e    Any curl options will be passed down to curl.\n\n## Configuration, Data File Locations\n\n\nResty creates a few files in either your `${XDG_CONFIG_HOME}` and `${XDG_DATA_HOME}`\ndirectory (if your linux uses the XDG directory standard) or in the `~/.resty`\ndirectory, otherwise.\n\n#### Using Existing, Pre-v2.1 Configuration Files With v2.1 ####\n\nIf you had resty installed before version 2.1 and your system uses the XDG\nconfig directory standard and you want to continue using your existing\nconfiguration files, please make a backup of your `~/.resty` directory\nand then do:\n\n      $ mkdir -p \"${XDG_CONFIG_HOME}/resty\" \"${XDG_DATA_HOME}/resty\"\n      $ mv ~/.resty/c \"${XDG_DATA_HOME}/resty\"\n      $ mv ~/.resty/* \"${XDG_CONFIG_HOME}/resty\"\n\n## Request URI Base\n\nThe request URI base is what the eventual URI to which the requests will be\nmade is based on. Specifically, it is a URI that may contain the `*` character\none or more times. The `*` will be replaced with the `path` parameter in the\n`OPTIONS`, `HEAD`, `GET`, `POST`, `PUT`, `PATCH`, or `DELETE` request as described\nabove.\n\nFor example:\n\n      $ resty 'http://127.0.0.1:8080/data*.json'\n      http://127.0.0.1:8080/data*.json\n\nand then\n\n      $ GET /5\n      { \"the_response\" : true }\n\nwould result in a `GET` request to the URI `http://127.0.0.1:8080/data/5.json`.\n\nIf no `*` character is specified when setting the base URI, it's just added\nonto the end for you automatically.\n\n### HTTPS URIs\n\nHTTPS URIs can be used, as well. For example:\n\n      $ resty 'https://example.com/doit'\n      https://example.com/doit*\n\n### URI Base History\n\nThe URI base is saved to an rc file (`${XDG_CONFIG_HOME}/resty/host` or `~/.resty/host`)\neach time it's set, and the last setting is saved in an environment variable\n(`$_resty_host`).  The URI base is read from the rc file when resty starts\nup, but only if the `$_resty_host` environment variable is not set.\nIn this way you can make requests to different hosts using resty from\nseparate terminals, and have a different URI base for each terminal.\n\nIf you want to see what the current URI base is, just run `resty` with no\narguments. The URI base will be printed to stdout.\n\n## The Optional Path Parameter\n\nThe HTTP verbs (`OPTIONS`, `HEAD`, `GET`, `POST`, `PUT`, `PATCH`, and `DELETE`)\nfirst argument is always an optional URI path. This path must always start with a\n`/` character. If the path parameter is not provided on the command line, resty\nwill just use the last path it was provided with. This \"last path\" is stored in an\nenvironment variable (`$_RESTY_PATH`), so each terminal basically has its\nown \"last path\".\n\nThis feature can be disabled with the following flag `RESTY_NO_PRESERVE_PATH=true`.\n\n### URL Encoding Of Path Parameter\n\nResty will always [URL encode]\n(http://www.blooberry.com/indexdot/html/topics/urlencoding.htm) the path,\nexcept for slashes. (Slashes in path elements need to be manually encoded as\n`%2F`.) This means that the `?`, `=`, and `\u0026` characters will be encoded, as\nwell as some other problematic characters. To disable this behavior use the\n`-Q` option.\n\n### Query Strings, POST Parameters, And Both At The Same Time\n\n\nThere are three ways to add a query string to the path. The first, mentioned\nabove, is to disable URL encoding with the `-Q` option, and include the\nquery string with the path parameter, like this:\n\n      $ GET '/blogs/47?param=foo\u0026otherparam=bar' -Q\n\nTo specify a query string without disabling URL encoding on the path the\n`-q` option is used, like this:\n\n      $ GET /blogs/47 -q 'param=foo\u0026otherparam=bar'\n\nFinally, you can use the curl `-d` and `-G` options, like this:\n\n      $ GET /blogs/47 -d 'param=foo' -d 'otherparam=bar' -G\n\nHowever, if you want to pass both GET parameters in the query string _and_\n`POST` parameters in the request body, curl cannot support this by itself.\nUsing the `-q` or `-Q` resty options with the `-d` curl option will accomplish\nthis, like so:\n\n      $ POST '/blogs/47?param=foo\u0026otherparam=bar' -Q -d 'postparam=baz'\n\n## POST/PUT/PATCH Requests and Data\n\nNormally you would probably want to provide the request body data right on\nthe command line like this:\n\n      $ PUT /blogs/5.json '{\"title\" : \"hello\", \"body\" : \"this is it\"}'\n\nBut sometimes you will want to send the request body from a file instead. To\ndo that you pipe in the contents of the file:\n\n      $ PUT /blogs/5.json \u003c /tmp/t\n\nOr you can pipe the data from another program, like this:\n\n      $ myprog | PUT /blogs/5.json\n\nOr, interestingly, as a filter pipeline with\n[jsawk](http://github.com/micha/jsawk):\n\n      $ GET /blogs/5.json | jsawk 'this.author=\"Bob Smith\";this.tags.push(\"news\")' | PUT\n\nNotice how the `path` argument is omitted from the `PUT` command.\n\n### Edit PUT/PATCH/POST Data In Vi\n\nWith the `-V` options you can pipe data into `PUT`, `PATCH`, or `POST`, edit\nit in vi, save the data (using `:wq` in vi, as normal) and the resulting data\nis then PUT, PATCH, or POSTed. This is similar to the way `visudo` works, for example.\n\n      $ GET /blogs/2 | PUT -V\n\nThis fetches the data and lets you edit it, and then does a PUT on the\nresource. If you don't like vi you can specify your preferred editor by\nsetting the `EDITOR` environment variable.\n\n## Errors and Output\n\nFor successful *2xx* responses, the response body is printed on stdout. You\ncan pipe the output to stuff, process it, and then pipe it back to resty,\nif you want.\n\nFor responses other than *2xx* the response body is dumped to stderr.\n\nIn either case, if the content type of the response is `text/html`, then\nresty will try to process the response through either `lynx`, `html2text`,\nor, finally, `cat`, depending on which of those programs are available on\nyour system.\n\n### Raw Output (-Z option)\n\nIf you don't want resty to process the output through lynx or html2text you\ncan use the `-Z` option, and get the raw output.\n\n## Passing Command Line Options To Curl\n\nAnything after the (optional) `path` and `data` arguments is passed on to\n`curl`.\n\nFor example:\n\n      $ GET /blogs.json -H \"Range: items=1-10\"\n\nThe `-H \"Range: items=1-10\"` argument will be passed to `curl` for you. This\nmakes it possible to do some more complex operations when necessary.\n\n      $ POST -v -u user:test\n\nIn this example the `path` and `data` arguments were left off, but `-v` and\n`-u user:test` will be passed through to `curl`, as you would expect.\n\nHere are some useful options to try:\n\n  - **-v** verbose output, shows HTTP headers and status on stderr\n  - **-j** junk session cookies (refresh cookie-based session)\n  - **-u \\\u003cusername:password\\\u003e** HTTP basic authentication\n  - **-H \\\u003cheader\\\u003e** add request header (this option can be added more than\n    once)\n\n### Setting The Default Curl Options\n\nSometimes you want to send some options to curl for every request. It\nwould be tedious to have to repeat these options constantly. To tell\n*resty* to always add certain curl options you can specify those options\nwhen you call resty to set the URI base. For example:\n\n      $ resty example.com:8080 -H \"Accept: application/json\" -u user:pass\n\nEvery subsequent request will have the `-H \"Accept:...\"` and `-u user:...`\noptions automatically added. Each time resty is called this option list\nis reset.\n\n### Per-Host/Per-Method Curl Configuration Files\n\n*Resty* supports a *per-host/per-method configuration* file to help you with\nfrequently used curl options. Each host (including the port) can have its\nown configuration file in the `~/.resty` directory.\nA special host `resty` is used to define *default* options for all the hosts.\n\nThe file format is\n\n      GET [arg] [arg] ...\n      PUT [arg] [arg] ...\n      PATCH [arg] [arg] ...\n      POST [arg] [arg] ...\n      DELETE [arg] [arg] ...\n\nWhere the `arg`s are curl command line arguments. Each line can specify\narguments for that HTTP verb only, and all lines are optional.\n\nThese config files are loaded each time you run the `resty` command.\n\n#### Example\nSo, suppose you find yourself using the same curl options over and over. You\ncan save them in a file and resty will pass them to curl for you. Say this\nis a frequent pattern for you:\n\n      $ resty localhost:8080\n      $ GET /Blah -H \"Accept: application/json\"\n      $ GET /Other -H \"Accept: application/json\"\n      ...\n      $ POST /Something -H \"Content-Type: text/plain\" -u user:pass\n      $ POST /SomethingElse -H \"Content-Type: text/plain\" -u user:pass\n      ...\n\nIt's annoying to add the `-H` and `-u` options to curl all the time. So\ncreate a file `~/.resty/localhost:8080`, like this:\n\n_~/.resty/localhost:8080_\n\n      GET -H \"Accept: application/json\"\n      POST -H \"Content-Type: text/plain\" -u user:pass\n\nThen any `GET` or `POST` requests to `localhost:8080` will have the specified\noptions prepended to the curl command line arguments, saving you from having\nto type them out each time, like this:\n\n      $ GET /Blah\n      $ GET /Other\n      ...\n      $ POST /Something\n      $ POST /SomethingElse\n      ...\n\nSweet! Much better.\n\n## Exit Status\n\nSuccessful requests (HTTP respose with *2xx* status) return zero.\nOtherwise, the first digit of the response status is returned (i.e., 1 for\n1xx, 3 for 3xx, 4 for 4xx, etc.) This is because the exit status is an 8 bit\ninteger---it can't be greater than 255. If you want the exact status code\nyou can always just pass the `-v` option to curl.\n\n## Using Resty In Shell Scripts\n\nSince resty creates the REST verb functions in the shell, when using it from a script you must `source` it before you use any of the functions. However, it's likely that you don't want it to be overwriting the resty host history file, and you will almost always want to set the URI base explicitly.\n\n      #!/usr/bin/env bash\n\n      # Load resty, don't write to the history file, and set the URI base\n      . /path/to/resty -W 'https://myhost.com/data*.json'\n\n      # GET the JSON list of users, set each of their 'disabled' properties\n      # to 'false', and PUT the modified JSON back\n      GET /users | jsawk 'this.disabled = false' | PUT\n\nHere the `-W` option was used when loading the script to prevent writing to the history file and an initial URI base was set at the same time. Then a JSON file was fetched, edited using [jsawk](http://github.com/micha/jsawk), and re-uploaded to the server.\n\nTo assign the response of resty to a variable you can you do for example: `VAR=\"$(GET /some/request)\"`. Note that the quote symbol (`\"`) around the subcommand is necessary if the output contains spaces.\n\n## Working With JSON or XML Data\n\n`JSON REST` web services require some special tools to make them accessible\nand easily manipulated in the shell environment. The following are a few\nscripts that make dealing with JSON data easier.\n\n  * The included `pp` script will pretty-print JSON for you. You just need to\n    install the JSON perl module from CPAN (included with brew install)\n    or you can use `pypp` if you have python installed.\n\n    `GET /blogs.json | pp   # pretty-prints the JSON output from resty`\n\n  * You can use powerful [jq](https://stedolan.github.io/jq/) Json command line\n    processor to perform operations on the received json. just pyping to `jq .`\n    will pretty print the json in color\n\n  * Another way to format JSON output:\n\n        $ echo '{\"json\":\"obj\"}' | python -mjson.tool\n        {\n          \"json\": \"obj\"\n        }\n\n  * [Jsawk](http://github.com/micha/jsawk) can be used to process and filter\n    JSON data from and to resty, in a shell pipeline. This takes care of\n    parsing the input JSON correctly, rather than using regexes and `sed`,\n    `awk`, `per`l or the like, and prints the resulting output in correct JSON\n    format, as well.\n\n    `GET /blogs.json | jsawk -n 'out(this.title)' # prints all the blog titles`\n\n\n  * The `tidy` tool can be used to format HTML/XML:\n\n        $ ~$ echo \"\u003ctest\u003e\u003cdeep\u003evalue\u003c/deep\u003e\u003c/test\u003e\" | tidy -xml -q -i\n        \u003ctest\u003e\n          \u003cdeep\u003evalue\u003c/deep\u003e\n        \u003c/test\u003e\n","funding_links":[],"categories":["Shell","Testing","Projects","\u003ca name=\"http\"\u003e\u003c/a\u003ehttp","others","Downloading and Serving","Programming Languages"],"sub_categories":["Querying","API Testing","Directory Navigation","Bash/Shell"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmicha%2Fresty","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmicha%2Fresty","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmicha%2Fresty/lists"}