lrclient-cli v0.0.8
LRestClient
Command-line, json-based REST-Client written in Typescript.
Usage
$ npm install -g lrclient
$ lrc COMMAND
running command...
$ lrc send ./endpoints/accounts/user/profile.json -v "user: lmnch"
Requesting...
GET http://www.github.com/lmnch/LRClient
Authorization: Bearer ...
User-Agent: Mozilla Firefox
...
Definitions
Variables
Variables can be used to parameterize your requests. The value of a variable can be references like this:
{{variablename}}
The value of a variable can be defined on different levels which overwrite each other in the following order (lower index overwrites higher index): 1. Local variables: These are variables that are passed directly at the call and might be used e.g. for dynamic values which are returned by another request 2. Endpoint variables: Defined at the endpoint which should be called 3. Environment variables: Defined for the currently selected environment
Variable values can contain other variables (but please do not create circular dependencies):
{
"variables": {
"username": "bernd",
"authorization": "{{username}}:{{password}}",
"password": "bernd!rocks"
}
}
(the variable authorization
will be resolved to bernd:bernd!rocks
)
Headers
There's a similar hierarchy like for variables: 1. Endpoint headers 2. Environment headers
Variables can be used inside of the value of a header:
{
"headers": {
"Authorization": "{{authorization}}"
},
"variables": {
"username": "bernd",
"authorization": "{{username}}:{{password}}",
"password": "bernd!rocks"
}
}
Payloads
A payload can be used by creating a json file of this form:
{
"payloadType": "application/json",
"data": "{\"street\":\"Teststreet\",\"name\": \"{{user}}\"}"
}
Inside of this data field, variables can be resolved. Currently, there are three types of payloads supported:
- JSON:
data
contains the whole JSON string - Text:
data
contains the whole text - Files:
data
contains the path to the file that should be uploaded
The payload which should be used for a request can be defined on two levels (similar to variables): 1. "Locally": Directly at the call via parameter 2. Endpoint: Default payload for the endpoint
The payload can be selected by refering it in the send command call lrc send ENDPOINT
.
Endpoint
The job of a REST-Client is obvoiusly to call REST-Endpoints. Such an endpoint is defined as following:
{
"url": "http://localhost:8080/api/upload",
"method": "POST",
"headers": {
"User-Agent": "Mozilla Firefox"
},
"variables": {
"user": "lmnch"
}
}
It consists of the mandatory fields: url (of course), the HTTP method that should be used and the resultType. Additionally, variables and headers can be defined optionally here. It is also possible to overwrite/supplement the headers and variables defined in the environment.
The endpoint file that should be used can be selected by its path when using the send command.
Environments
The LRClient can be configured by using different environments. An environment contains headers and custom variables which are applied to all request executed with the enviroment.
{
"headers": {
"Authorization": "Bearer {{bearerToken}}",
"User-Agent": "Mozilla Firefox"
},
"variables": {
"bearerToken": "...",
"baseUrl": "http://www.github.com",
"user": "lmnch",
"repository": "LRClient",
"requestUrl": "{{baseUrl}}/{{user}}/{{repository}}"
}
}
Currently, the environment has to be defined directly in a JSON file.
But, one can switch between different files with the lrc env set
command.
Commands
lrc env set
Changes the currently used environment.
USAGE
$ lrc env set ./env/production.json
...
Following rest calls are going to use the environment file "./env/production.json"
lrc env get
Returns the currently used environment.
USAGE
$ lrc env get
./env/production.json
Headers:
Authorization: Bearer {{bearerToken}}
User-Agent: Mozilla Firefox
Variables:
bearerToken=...
baseUrl=http://www.github.com
user=lmnch
repository=LRClient
requestUrl={{baseUrl}}/{{user}}/{{repository}}
lrc send ENDPOINT
Performs a rest call to the endpoint defined in the ENDPOINT
file.
Therefore, all variables are resolved (see Variables
).
Additional variables can be passed with --localVariable "key: value"
or -v "key: value
(can be used multiple times).
USAGE:
$ lrc send ./module1/request1.json --localVariable "user: lukas"
production
Headers:
Authorization: Bearer {{bearerToken}}
User-Agent: Mozilla Firefox
Variables:
bearerToken=...
baseUrl=http://www.github.com
user=lmnch
repository=LRClient
requestUrl={{baseUrl}}/{{user}}/{{repository}}
module1/request1
GET {{requestUrl}}
Requesting...
GET http://www.github.com/lukas/LRClient
Authorization: Bearer ...
User-Agent: Mozilla Firefox
// TODO: Add result
lrc payload new PAYLOAD
Creates a new payload definition file at ./PAYLOAD
.
It is possble to choose the the payload type upfront.
Then, the editor defined in the $EDITOR
environment variable is launched to enter the data for the payload.
USAGE:
$ lrc payload new payloads/example.json
Which type of payload should be created?
(x) application/json
( ) application/text
( ) application/octet-stream
( ) application/pdf
*opens editor*
Type: application/json
{
"test": 123
}
lrc payload edit PAYLOAD
Edits the data of the payload definition file at ./PAYLOAD
.
The editor defined in the $EDITOR
environment variable is launched to enter the data for the payload.
USAGE:
$ lrc payload edit payloads/example.json
*opens editor*
Type: application/json
{
"test": 123
}
lrc script execute SCRIPTFILE
Executes the ECMA script file that is located at the passed position.
Inside of these script files, the variables lrc
- which is an instance of the LRClient
- and log
- which is a function like console.log
- can be used.
Furthermore, the await keyword can be used to wait for the result of lrc.send
.
Example
let password = "test";
// Creates a new user
const createdUser = await lrc.send("./endpoints/create-new-user.json", { name: "lukas", password: password });
// Update the user's password 10 times
for(let i = 0; i < 10; i++){
let newPassword = password;
await lrc.send("./endpoints/update-password.json", {name: "lukas", oldPassword: password, newPassword: newPassword});
password = newPassword;
}
Implementation
Internally, the imported script is wrapped in a async function with lrc
and log
as parameters.
These values are passed to the context of the execution.
So internally, the example from before results in the following snippet:
const executionLrcMethod = async (lrc) => {
let password = "test";
// Creates a new user
const createdUser = await lrc.send("./endpoints/create-new-user.json", { name: "lukas", password: password });
// Update the user's password 10 times
for(let i = 0; i < 10; i++){
let newPassword = password;
await lrc.send("./endpoints/update-password.json", {name: "lukas", oldPassword: password, newPassword: newPassword});
password = newPassword;
}
};
executionLrcMethod(lrc, log);
This allows the usage of the await
keyword in the script files.
Logging
For all the request sending commands (lrc send ENDPOINT
and lrc script execute SCRIPTFILE
), the default logging behaviour can be overwritten by using the loggedFields
flag (or the alias -l
).
Multiple values can be passed using this flag:
env
: Logs the current environment before executing the request (this contains headers and variables)endpoint
: Logs the endpoint definition which was selected (contains basic information like url but also variables and headers)endpoint_payload
: Logs the payload which is linked in the endpointreq
: Logs the resulting request after variable resolutionreq_body
: Logs the resulting body after variable replacementresp
: Logs information about the response like status coderesp_body
: Logs the extracted body of the response
The lrc send ENDPOINT
command uses per default the logging flags req
, req_body
, resp
, and resp_body
.
The lrc script execute SCRIPTFILE
) command (logging flags apply to all requests made by the script) logs per default nothing.
Setting one of the flags as parameter in the cli overwrites the default behaviour what means the default flags won't be logged (if they are not specified again manually).
Project structure
The project uses The Open CLI Framework to provide the REST client as cli tool.
The source files for the commands are stored in src/commands
.
The commands call the configuration and REST client functionality by using the classes in the src/boundary
directory.
It contains the LRClient
which performs the REST calls and the ConfigManager
which allows to load and change the configuration.
src/model
contains the data classes that define how the requests are performed.
This contains some enums (HttpMethod
, PayloadType
) and classes that contain the definition (Environment
, Endpoint
).
Further, theres a special directory payload
for different payload types.
They use classes from the src/variables
directory which manage the variables and variable replacement.
The LRCLogger
(src/logging/LRCLogger
) is used to print the model classes to the console in a colorful way.
All commands (generated)
lrc BaseCommand
lrc ee ENDPOINT
lrc en ENDPOINT
lrc endpoint edit ENDPOINT
lrc endpoint new ENDPOINT
lrc env get
lrc env set ENVIRONMENT
lrc help [COMMAND]
lrc payload edit PAYLOAD
lrc payload new PAYLOAD
lrc pe PAYLOAD
lrc plugins
lrc plugins:install PLUGIN...
lrc plugins:inspect PLUGIN...
lrc plugins:install PLUGIN...
lrc plugins:link PLUGIN
lrc plugins:uninstall PLUGIN...
lrc plugins:uninstall PLUGIN...
lrc plugins:uninstall PLUGIN...
lrc plugins update
lrc pn PAYLOAD
lrc script execute SCRIPT
lrc se SCRIPT
lrc send REQUESTPATH
lrc BaseCommand
USAGE
$ lrc BaseCommand [--loggedFields env|endpoint|endpoint_payload|req|req_body|resp|resp_body] [--config <value>]
GLOBAL FLAGS
--config=<value> Path to the lrc config file. Can be
also set via LRC_CONFIG_FILE env const
and is per default './.config'
--loggedFields=(env|endpoint|endpoint_payload|req|req_body|resp|resp_body)... Specify level for logging.
See code: dist/commands/BaseCommand.ts
lrc ee ENDPOINT
Updates the endpoint configuration file in the editor set in $EDITOR variable.
USAGE
$ lrc ee [ENDPOINT]
ARGUMENTS
ENDPOINT Path to the endpoint definition json file
DESCRIPTION
Updates the endpoint configuration file in the editor set in $EDITOR variable.
ALIASES
$ lrc ee
EXAMPLES
$ lrc ee endpoints/example.json
endpoints/test.json
* Editor opens *
PUT {{url}}/api
{
"billo": "test"
}
lrc en ENDPOINT
Creates a new endpoint definition file.
USAGE
$ lrc en [ENDPOINT] [-u <value>] [-m <value>] [-h <value>] [-v <value>] [-p <value>]
ARGUMENTS
ENDPOINT Path to the endpoint definition json file
FLAGS
-h, --headers=<value>... Headers that should be used when calling the endpoint.
-m, --method=<value> HTTP method for the request (GET, POST, PUT, DELETE, PATCH, HEAD, CONNECT, TRACE).
-p, --payload=<value> Path to payload for the endpoint.
-u, --url=<value> URL of the endpoint (Could contain variables).
-v, --localVariable=<value>... Variables for the endpoint.
DESCRIPTION
Creates a new endpoint definition file.
ALIASES
$ lrc en
EXAMPLES
$ lrc en endpoints/example.json
URL: {{baseUrl}}/test
HTTP Method:
POST
Create new payload (y/n): n
endpoints/example.json
POST {{baseUrl}}/test
$ lrc en endpoints/example.json
URL: {{baseUrl}}/api/test
HTTP Method:
PUT
Create new payload (y/n): y
Payload Path: payloads/data/test.json
Payload Type:
application/json
Type: application/json
{
"billo": "moin"
}
endpoints/example.json
PUT {{baseUrl}}/api/test
lrc endpoint edit ENDPOINT
Updates the endpoint configuration file in the editor set in $EDITOR variable.
USAGE
$ lrc endpoint edit [ENDPOINT]
ARGUMENTS
ENDPOINT Path to the endpoint definition json file
DESCRIPTION
Updates the endpoint configuration file in the editor set in $EDITOR variable.
ALIASES
$ lrc ee
EXAMPLES
$ lrc endpoint edit endpoints/example.json
endpoints/test.json
* Editor opens *
PUT {{url}}/api
{
"billo": "test"
}
lrc endpoint new ENDPOINT
Creates a new endpoint definition file.
USAGE
$ lrc endpoint new [ENDPOINT] [-u <value>] [-m <value>] [-h <value>] [-v <value>] [-p <value>]
ARGUMENTS
ENDPOINT Path to the endpoint definition json file
FLAGS
-h, --headers=<value>... Headers that should be used when calling the endpoint.
-m, --method=<value> HTTP method for the request (GET, POST, PUT, DELETE, PATCH, HEAD, CONNECT, TRACE).
-p, --payload=<value> Path to payload for the endpoint.
-u, --url=<value> URL of the endpoint (Could contain variables).
-v, --localVariable=<value>... Variables for the endpoint.
DESCRIPTION
Creates a new endpoint definition file.
ALIASES
$ lrc en
EXAMPLES
$ lrc endpoint new endpoints/example.json
URL: {{baseUrl}}/test
HTTP Method:
POST
Create new payload (y/n): n
endpoints/example.json
POST {{baseUrl}}/test
$ lrc endpoint new endpoints/example.json
URL: {{baseUrl}}/api/test
HTTP Method:
PUT
Create new payload (y/n): y
Payload Path: payloads/data/test.json
Payload Type:
application/json
Type: application/json
{
"billo": "moin"
}
endpoints/example.json
PUT {{baseUrl}}/api/test
lrc env get
Returns the currently selected environment.
USAGE
$ lrc env get
DESCRIPTION
Returns the currently selected environment.
EXAMPLES
$ lrc env get
./env/test.json
Headers:
Authorization: Bearer {{bearerToken}}
User-Agent: Mozilla Firefox
Variables:
bearerToken=...
baseUrl=http://www.github.com
user=lmnch
repository=LRClient
requestUrl={{baseUrl}}/{{user}}/{{repository}}
lrc env set ENVIRONMENT
Updates the current working environment
USAGE
$ lrc env set [ENVIRONMENT]
ARGUMENTS
ENVIRONMENT Path to the environment json file
DESCRIPTION
Updates the current working environment
EXAMPLES
$ lrc env set ./env/test.json
./env/test.json
Headers:
Authorization: Bearer {{bearerToken}}
User-Agent: Mozilla Firefox
Variables:
bearerToken=...
baseUrl=http://www.github.com
user=lmnch
repository=LRClient
requestUrl={{baseUrl}}/{{user}}/{{repository}}
Updated config ⚙️
lrc help [COMMAND]
Display help for lrc.
USAGE
$ lrc help [COMMAND] [-n]
ARGUMENTS
COMMAND Command to show help for.
FLAGS
-n, --nested-commands Include all nested commands in the output.
DESCRIPTION
Display help for lrc.
See code: @oclif/plugin-help
lrc payload edit PAYLOAD
Updates the payload data of the passed payload definition
USAGE
$ lrc payload edit [PAYLOAD]
ARGUMENTS
PAYLOAD Path to the payload definition json file
DESCRIPTION
Updates the payload data of the passed payload definition
ALIASES
$ lrc pe
EXAMPLES
$ lrc payload edit payloads/example.json
*opens editor*
Type: application/json
{
"test": 123
}
lrc payload new PAYLOAD
Creates a new payload configuration file
USAGE
$ lrc payload new [PAYLOAD] [-t <value>]
ARGUMENTS
PAYLOAD Path to the payload definition json file
FLAGS
-t, --payloadType=<value> Type of the payload (application/json, application/text, application/octet-stream,
application/pdf)
DESCRIPTION
Creates a new payload configuration file
ALIASES
$ lrc pn
EXAMPLES
$ lrc payload new payloads/example.json
Which type of payload should be created?
(x) application/json
( ) application/text
( ) application/octet-stream
( ) application/pdf
*opens editor*
Type: application/json
{
"test": 123
}
lrc pe PAYLOAD
Updates the payload data of the passed payload definition
USAGE
$ lrc pe [PAYLOAD]
ARGUMENTS
PAYLOAD Path to the payload definition json file
DESCRIPTION
Updates the payload data of the passed payload definition
ALIASES
$ lrc pe
EXAMPLES
$ lrc pe payloads/example.json
*opens editor*
Type: application/json
{
"test": 123
}
lrc plugins
List installed plugins.
USAGE
$ lrc plugins [--core]
FLAGS
--core Show core plugins.
DESCRIPTION
List installed plugins.
EXAMPLES
$ lrc plugins
See code: @oclif/plugin-plugins
lrc plugins:install PLUGIN...
Installs a plugin into the CLI.
USAGE
$ lrc plugins:install PLUGIN...
ARGUMENTS
PLUGIN Plugin to install.
FLAGS
-f, --force Run yarn install with force flag.
-h, --help Show CLI help.
-v, --verbose
DESCRIPTION
Installs a plugin into the CLI.
Can be installed from npm or a git url.
Installation of a user-installed plugin will override a core plugin.
e.g. If you have a core plugin that has a 'hello' command, installing a user-installed plugin with a 'hello' command
will override the core plugin implementation. This is useful if a user needs to update core plugin functionality in
the CLI without the need to patch and update the whole CLI.
ALIASES
$ lrc plugins add
EXAMPLES
$ lrc plugins:install myplugin
$ lrc plugins:install https://github.com/someuser/someplugin
$ lrc plugins:install someuser/someplugin
lrc plugins:inspect PLUGIN...
Displays installation properties of a plugin.
USAGE
$ lrc plugins:inspect PLUGIN...
ARGUMENTS
PLUGIN [default: .] Plugin to inspect.
FLAGS
-h, --help Show CLI help.
-v, --verbose
DESCRIPTION
Displays installation properties of a plugin.
EXAMPLES
$ lrc plugins:inspect myplugin
lrc plugins:install PLUGIN...
Installs a plugin into the CLI.
USAGE
$ lrc plugins:install PLUGIN...
ARGUMENTS
PLUGIN Plugin to install.
FLAGS
-f, --force Run yarn install with force flag.
-h, --help Show CLI help.
-v, --verbose
DESCRIPTION
Installs a plugin into the CLI.
Can be installed from npm or a git url.
Installation of a user-installed plugin will override a core plugin.
e.g. If you have a core plugin that has a 'hello' command, installing a user-installed plugin with a 'hello' command
will override the core plugin implementation. This is useful if a user needs to update core plugin functionality in
the CLI without the need to patch and update the whole CLI.
ALIASES
$ lrc plugins add
EXAMPLES
$ lrc plugins:install myplugin
$ lrc plugins:install https://github.com/someuser/someplugin
$ lrc plugins:install someuser/someplugin
lrc plugins:link PLUGIN
Links a plugin into the CLI for development.
USAGE
$ lrc plugins:link PLUGIN
ARGUMENTS
PATH [default: .] path to plugin
FLAGS
-h, --help Show CLI help.
-v, --verbose
DESCRIPTION
Links a plugin into the CLI for development.
Installation of a linked plugin will override a user-installed or core plugin.
e.g. If you have a user-installed or core plugin that has a 'hello' command, installing a linked plugin with a 'hello'
command will override the user-installed or core plugin implementation. This is useful for development work.
EXAMPLES
$ lrc plugins:link myplugin
lrc plugins:uninstall PLUGIN...
Removes a plugin from the CLI.
USAGE
$ lrc plugins:uninstall PLUGIN...
ARGUMENTS
PLUGIN plugin to uninstall
FLAGS
-h, --help Show CLI help.
-v, --verbose
DESCRIPTION
Removes a plugin from the CLI.
ALIASES
$ lrc plugins unlink
$ lrc plugins remove
lrc plugins:uninstall PLUGIN...
Removes a plugin from the CLI.
USAGE
$ lrc plugins:uninstall PLUGIN...
ARGUMENTS
PLUGIN plugin to uninstall
FLAGS
-h, --help Show CLI help.
-v, --verbose
DESCRIPTION
Removes a plugin from the CLI.
ALIASES
$ lrc plugins unlink
$ lrc plugins remove
lrc plugins:uninstall PLUGIN...
Removes a plugin from the CLI.
USAGE
$ lrc plugins:uninstall PLUGIN...
ARGUMENTS
PLUGIN plugin to uninstall
FLAGS
-h, --help Show CLI help.
-v, --verbose
DESCRIPTION
Removes a plugin from the CLI.
ALIASES
$ lrc plugins unlink
$ lrc plugins remove
lrc plugins update
Update installed plugins.
USAGE
$ lrc plugins update [-h] [-v]
FLAGS
-h, --help Show CLI help.
-v, --verbose
DESCRIPTION
Update installed plugins.
lrc pn PAYLOAD
Creates a new payload configuration file
USAGE
$ lrc pn [PAYLOAD] [-t <value>]
ARGUMENTS
PAYLOAD Path to the payload definition json file
FLAGS
-t, --payloadType=<value> Type of the payload (application/json, application/text, application/octet-stream,
application/pdf)
DESCRIPTION
Creates a new payload configuration file
ALIASES
$ lrc pn
EXAMPLES
$ lrc pn payloads/example.json
Which type of payload should be created?
(x) application/json
( ) application/text
( ) application/octet-stream
( ) application/pdf
*opens editor*
Type: application/json
{
"test": 123
}
lrc script execute SCRIPT
Executes a ECMA script by providing LRClient as "lrc" variable in the context of an async method (=> "await" can be used). Additionally "log" can be used to log stuff like "console.log" (but this one is not working).
USAGE
$ lrc script execute [SCRIPT] [--loggedFields env|endpoint|endpoint_payload|req|req_body|resp|resp_body] [--config
<value>]
ARGUMENTS
SCRIPT Path to script that should be executed
GLOBAL FLAGS
--config=<value> Path to the lrc config file. Can be
also set via LRC_CONFIG_FILE env const
and is per default './.config'
--loggedFields=(env|endpoint|endpoint_payload|req|req_body|resp|resp_body)... Specify level for logging.
DESCRIPTION
Executes a ECMA script by providing LRClient as "lrc" variable in the context of an async method (=> "await" can be
used). Additionally "log" can be used to log stuff like "console.log" (but this one is not working).
ALIASES
$ lrc se
EXAMPLES
$ lrc script execute ./scripts/testscript.js
lrc se SCRIPT
Executes a ECMA script by providing LRClient as "lrc" variable in the context of an async method (=> "await" can be used). Additionally "log" can be used to log stuff like "console.log" (but this one is not working).
USAGE
$ lrc se [SCRIPT] [--loggedFields env|endpoint|endpoint_payload|req|req_body|resp|resp_body] [--config
<value>]
ARGUMENTS
SCRIPT Path to script that should be executed
GLOBAL FLAGS
--config=<value> Path to the lrc config file. Can be
also set via LRC_CONFIG_FILE env const
and is per default './.config'
--loggedFields=(env|endpoint|endpoint_payload|req|req_body|resp|resp_body)... Specify level for logging.
DESCRIPTION
Executes a ECMA script by providing LRClient as "lrc" variable in the context of an async method (=> "await" can be
used). Additionally "log" can be used to log stuff like "console.log" (but this one is not working).
ALIASES
$ lrc se
EXAMPLES
$ lrc se ./scripts/testscript.js
lrc send REQUESTPATH
Performs a REST call to a endpoint
USAGE
$ lrc send [REQUESTPATH] [--loggedFields env|endpoint|endpoint_payload|req|req_body|resp|resp_body]
[--config <value>] [-v <value>] [-p <value>]
ARGUMENTS
REQUESTPATH Path to the endpoint defintion json file that should be called
FLAGS
-p, --payload=<value> Path to the payload which should be used for the request
-v, --localVariable=<value>... Local variables to overwrite endpoint or environment variables
GLOBAL FLAGS
--config=<value> Path to the lrc config file. Can be
also set via LRC_CONFIG_FILE env const
and is per default './.config'
--loggedFields=(env|endpoint|endpoint_payload|req|req_body|resp|resp_body)... Specify level for logging.
DESCRIPTION
Performs a REST call to a endpoint
EXAMPLES
$ lrc send endpoints/examplerequest.json --localVariable "user: lukas"
Requesting...
POST http://www.google.com/lukas/LRClient
Authorization: Bearer ...
User-Agent: Mozilla Firefox
Response:
404 Not Found
content-length: 1575
content-type: text/html; charset=UTF-8
date: Sat, 19 Nov 2022 09:33:10 GMT
referrer-policy: no-referrer
<!DOCTYPE html>
<html lang=en>
...
$ lrc send endpoints/examplerequest.json
Requesting...
POST http://www.google.com/lmnch/LRClient
Authorization: Bearer ...
User-Agent: Mozilla Firefox
Response:
404 Not Found
content-length: 1575
content-type: text/html; charset=UTF-8
date: Sat, 19 Nov 2022 09:31:37 GMT
referrer-policy: no-referrer
<!DOCTYPE html>
<html lang=en>
...
See code: dist/commands/send/index.ts