{"id":19958204,"url":"https://github.com/zimmermanncode/restline","last_synced_at":"2026-05-12T00:38:58.119Z","repository":{"id":143906386,"uuid":"95795289","full_name":"zimmermanncode/restline","owner":"zimmermanncode","description":"RESTline\u003e make RESTful Vorpal commands","archived":false,"fork":false,"pushed_at":"2017-07-09T18:30:11.000Z","size":33,"stargazers_count":1,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-02-12T23:14:59.542Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","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/zimmermanncode.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGES.md","contributing":null,"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,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-06-29T16:05:51.000Z","updated_at":"2017-11-15T07:55:39.000Z","dependencies_parsed_at":null,"dependency_job_id":"b49552ed-256d-49e0-8621-3aaed67b177b","html_url":"https://github.com/zimmermanncode/restline","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zimmermanncode%2Frestline","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zimmermanncode%2Frestline/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zimmermanncode%2Frestline/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zimmermanncode%2Frestline/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zimmermanncode","download_url":"https://codeload.github.com/zimmermanncode/restline/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241389166,"owners_count":19955107,"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-11-13T01:41:24.090Z","updated_at":"2026-05-12T00:38:58.093Z","avatar_url":"https://github.com/zimmermanncode.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# RESTline\u003e make RESTful Vorpal commands\r\n\r\n[![](https://img.shields.io/npm/v/restline.svg)](\r\n  https://www.npmjs.com/package/restline)\r\n[![](https://img.shields.io/npm/dt/restline.svg)](\r\n  https://www.npmjs.com/package/restline)\r\n\r\n```javascript\r\nvar vorpal = require('vorpal')(),\r\n    RESTline = require('restline')(vorpal);\r\n\r\nvorpal.show();\r\n```\r\n\r\nIn parallel to [vorpal.command(command [, description])](\r\n  https://github.com/dthree/vorpal/wiki/api-%7C-vorpal.command) you can now\r\neasily create commands that do REST operations in the background via\r\n`RESTline.command(...)`, which takes the same arguments. But first,\r\n`RESTline` needs a host to send REST requests to. You can either define a\r\n`.https(host [, port])` or a `.http(host [,port])`.\r\n\r\n```javascript\r\nRESTline.https('api.npms.io');\r\n```\r\n\r\nThe default `port` for `.https` is `443`, for `.http` it defaults to `80`.\r\n\r\nYou can also directly set `RESTline.host('...')` and `RESTline.port(...)`\r\nwithout changing the protocol, which defaults to HTTP.\r\n\r\nFor authentication there is `RESTline.user('...')` and\r\n`RESTline.password('...')`.\r\n\r\nLet's create some commands to work with the https://api.npms.io API:\r\n\r\n```javascript\r\nRESTline.command(\"npm vorpal\",\r\n                 \"Show information for latest release of vorpal package\")\r\n    .GET(\"v2/package/vorpal\");\r\n```\r\n\r\n`RESTline.command(...).GET(handler [, query [, status]])` will automatically\r\ncreate a [vorpal.command(...)](\r\n  https://github.com/dthree/vorpal/wiki/api-%7C-vorpal.command#vorpalcommandcommand-description)\r\nand a [vorpal.command(...).action(function ...)](\r\n  https://github.com/dthree/vorpal/wiki/api-%7C-vorpal.command#commandactionfunction),\r\nand returns the `vorpal.command(...)` instance, so you can further chain it\r\nwith every other Vorpal [Command](\r\n  https://github.com/dthree/vorpal/wiki/api-%7C-vorpal.command#api) method.\r\n\r\nSince the `handler` is just a `string`in the above case, calling the command\r\nwill send a GET request via [superagent](\r\n  https://www.npmjs.com/package/superagent)\r\nto https://api.npms.io/v2/package/vorpal and print the JSON response:\r\n\r\n```\r\n$ npm vorpal\r\n{\r\n  ...\r\n  \"collected\": {\r\n    \"metadata\": {\r\n      \"name\": \"vorpal\",\r\n      \"scope\": \"unscoped\",\r\n      \"version\": \"1.12.0\",\r\n      \"description\": \"Node's first framework for building immersive CLI apps.\",\r\n      ...\r\n      },\r\n    ...\r\n  },\r\n  ...\r\n}\r\n```\r\n\r\nNow we want a command that takes a package name as parameter. For that purpose\r\nyou can also pass a `handler` function to `RESTline.command(...).GET`, which\r\nis called with `this` of `vorpal.command(\"...\").action(function ...)`, and the\r\nVorpal command `args` and an internal RESTline\r\n`GET(path [, query [, status]])` function, which does the actual REST request:\r\n\r\n```javascript\r\nRESTline.command(\"npm package \u003cname\u003e\",\r\n                 \"Show information for latest version of given package\")\r\n    .GET(function (args, GET) {\r\n        GET(\"v2/package/\" + args.name);\r\n    });\r\n```\r\n\r\n```\r\n$ npm package superagent\r\n{\r\n  ...\r\n  \"collected\": {\r\n    \"metadata\": {\r\n      \"name\": \"superagent\",\r\n      \"scope\": \"unscoped\",\r\n      \"version\": \"3.5.2\",\r\n      \"description\": \"elegant \u0026 feature rich browser / node HTTP with a fluent API\",\r\n      ...\r\n      },\r\n    ...     \r\n  },\r\n  ...\r\n}\r\n```\r\n\r\nYou might need `query` variables at the end of your URL:\r\n\r\n```javascript\r\nRESTline.command(\"npm search \u003cstring\u003e\")\r\n    .GET(function (args, GET) {\r\n        GET(\"v2/search\", {q: args.string});\r\n    });\r\n```\r\n\r\nCalling the command with `vorpal` as `\u003cstring\u003e` argument will send a GET\r\nrequest to `https://api.npms.io/v2/search?q=vorpal`:\r\n\r\n```\r\n$ npm search vorpal\r\n{\r\n    \"total\": 56,\r\n    \"results\": [\r\n        {\r\n            \"package\": {\r\n                \"name\": \"vorpal\",\r\n                \"scope\": \"unscoped\",\r\n                \"version\": \"1.12.0\",\r\n                \"description\": \"Node's first framework for building immersive CLI apps.\",\r\n                ...\r\n            },\r\n            ...\r\n        },\r\n        ...\r\n    ]\r\n}\r\n```\r\n\r\nThe REST response status is not always fine:\r\n\r\n```\r\n$ npm package non-existent\r\nError: Not Found (404)\r\n```\r\n\r\nYou can accept that standard error output or define custom `status` handlers.\r\nThey can be either simple message strings or handler functions, that will be\r\ncalled with `this` of `vorpal.command(\"...\").action(function ...)` and `args`\r\nand the [superagent](https://www.npmjs.com/package/superagent) REST `result`\r\nas arguments. Let's redefine `npm package` with two verbosity flag:\r\n\r\n```javascript\r\nvorpal.find('npm package').remove();\r\n\r\nRESTline.command(\"npm package \u003cname\u003e\",\r\n                 \"Show information for latest version of given package\")\r\n    .option('-v, --verbose', \"Be verbose on errors\")\r\n    .option('-V, --very-verbose', \"Be even more verbose on errors\")\r\n    .GET(function (args, GET) {\r\n        GET(\"v2/package/\" + args.name, null,\r\n            args.options['very-verbose'] ? {\r\n                404: function (args, result) {\r\n                    this.log(\"Oops! \" + result.status +\r\n                             \"! Seems like package '\" + args.name +\r\n                             \"' was not found!\")\r\n                }\r\n            } : args.options.verbose ? {\r\n                404: \"Oops! Package not found!\"\r\n            } : null);\r\n    });\r\n```\r\n\r\n```\r\n$ npm package -v non-existent\r\nOops! Package not found!\r\n```\r\n\r\n```\r\n$ npm package -V non-existent\r\nOops! 404! Seems like package 'non-existent' was not found!\r\n```\r\n\r\nEnough of `.GET`! Let's do a\r\n`RESTline.command(...).POST(handler [, query [, data [, status]]])`.\r\nIt takes an additional `data` argument between `query` and `status`, which\r\ndefines the POST data to be sent. If `handler` is a function, it will also be\r\ncalled with `this` of `vorpal.command(\"...\").action(function ...)`, and the\r\nVorpal command `args` and in this case an internal `POST` function that takes\r\nthe same arguments as `RESTline.command(...).POST`:\r\n\r\n```javascript\r\nRESTline.command(\"npm mget \u003cnames...\u003e\")\r\n    .POST(function (args, POST) {\r\n        POST(\"v2/package/mget\", null, args.names);\r\n    });\r\n```\r\n\r\n```\r\n$ npm mget vorpal superagent\r\n{                                                                                        \r\n    \"vorpal\": {\r\n        ...\r\n        \"collected\": {\r\n            \"metadata\": {\r\n                \"name\": \"vorpal\",\r\n                \"scope\": \"unscoped\",\r\n                \"version\": \"1.12.0\",\r\n                \"description\": \"Node's first framework for building immersive CLI apps.\",\r\n                ...\r\n            },\r\n            ...\r\n        },\r\n    ...\r\n    },\r\n    \"superagent\": {\r\n        ...\r\n        \"collected\": {\r\n            \"metadata\": {\r\n                \"name\": \"superagent\",\r\n                \"scope\": \"unscoped\",\r\n                \"version\": \"3.5.2\",\r\n                \"description\": \"elegant \u0026 feature rich browser / node HTTP with a fluent API\",\r\n                ...\r\n            },\r\n            ...\r\n        },\r\n    ...\r\n    }\r\n}\r\n```\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzimmermanncode%2Frestline","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzimmermanncode%2Frestline","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzimmermanncode%2Frestline/lists"}