json-rpc-shell/json-rpc-shell.adoc

6.2 KiB
Raw Blame History

json-rpc-shell(1)

Name

json-rpc-shell - a shell for JSON-RPC 2.0

Synopsis

json-rpc-shell [OPTION]…​ { ENDPOINT | COMMAND [ARG]…​ }

Description

The ENDPOINT must be either an HTTP or a WebSocket URL, with or without TLS (i.e. one of the http://, https://, ws://, wss:// schemas).

json-rpc-shell will use it to send any JSON-RPC 2.0 requests you enter on its command line. The servers response will be parsed and validated, stripping it of the protocols noisy envelope. At your option, it can then also be pretty-printed, rendered with adjustable syntax highlighting, or even piped through another program such as the less(1) pager or the jq(1) JSON processor.

Usage

Three things may appear on the internal command line, in a sequence. The first one is always the name of the JSON-RPC method to call, as a bare word, separated from the rest by white space. Following that, you may enter three kinds of JSON values. If it is an object or an array, it constitutes the method parameters. If it is a string or a number, it is taken as the "id" to use for the request, which would be chosen for you automatically if left unspecified. Finally, a null value indicates that the request should be sent as a notification, lacking the ID completely. Booleans cannot be used for anything.

The response to the method call may be piped through external commands, the same way you would do it in a Unix shell.

Exit the program by pressing C-c or C-d. No special keywords are reserved for this action as they might conflict with method names.

Options

Controlling output

-c, --compact-output

Do not pretty-print responses. Normally, spaces and newlines are added where appropriate to improve readability.

--color=WHEN

By default, when the output of the program is a terminal, JSON responses are syntax-highlighted. This corresponds to the auto setting. You may also set this to always or never. In either case, color is never applied when piping to another program.

-v, --verbose

Print raw requests and responses, including the JSON-RPC 2.0 envelope.

-d, --debug

Print even more information to help debug various issues.

Protocol

-n, --null-as-id

Normally, entering a null JSON value on the command line causes a notification to be sent. With this option, it is sent as the "id" field of a normal request, which is discouraged by the specification.

-t, --trust-all

Trust all SSL/TLS certificates. Useful in case that the certificate is self-signed, or when the CA isnt in your CA store. Beware that this option is about as good as using plain unencrypted HTTP.

-o ORIGIN, --origin=ORIGIN

Set the HTTP Origin header to ORIGIN. Some servers may need this.

-O[PATH], --openrpc[=PATH]

Call "rpc.discover" upon start-up in order to pull in OpenRPC data for tab completion of method names. If a path is given, it is read from a file.

-e, --execute

Rather than an ENDPOINT, accept a command line to execute and communicate with using the JSON-RPC 2.0 protocol variation used in the Language Server Protocol.

Program information

-h, --help

Display a help message and exit.

-V, --version

Output version information and exit.

--write-default-cfg[=PATH]

Write a default configuration file, show its path and exit.

Files

~/.config/json-rpc-shell/json-rpc-shell.conf

The configuration file, in which you can configure color output and CA certificate paths. Use the --write-default-cfg option to create a new one for editing.

~/.local/share/json-rpc-shell/history

All your past method invocations are stored here upon exit and loaded back on start-up.

Notes

Editing

While single-line editing on the command line may be satisfactory for simple requests, it is often convenient or even necessary to run a full text editor in order to construct complex objects or arrays, and may even be used to import data from elsewhere. You can launch an editor for the current request using the M-e key combination. Both readline(3) and editline(7) also support multiline editing natively, press either M-Enter or C-v C-j in order to insert newlines.

WebSocket

The JSON-RPC 2.0 specification doesnt say almost anything about underlying transports. The way its implemented here is that every request is sent as a single text message. If it has an "id" field, i.e., its not just a notification, the client waits for a message from the server in response. Should any message arrive unexpectedly, you will receive a warning.

There is no support so far for any protocol extensions, nor for specifying the higher-level protocol (the "Sec-Ws-Protocol" HTTP field).

Bugs

The editline (libedit) frontend is more of a proof of concept that mostly seems to work but exhibits bugs that are not our fault.

Examples

Running some queries against json-rpc-test-server, included in the source distribution of this program (public services are hard to find):

Methods without parameters

$ json-rpc-shell ws://localhost:1234
json-rpc> ping
"pong"
json-rpc> date
{
  "year": 2020,
  "month": 9,
  "day": 5,
  "hours": 2,
  "minutes": 23,
  "seconds": 51
}

Notification with a parameter

Notifications never produce a response, not even when the method is not known to the server:

$ json-rpc-shell ws://localhost:1234
json-rpc> notify {"events": ["conquest", "war", "famine", "death"]} null
[Notification]

Piping in and out

GNU Readline always repeats the prompt, which makes this a bit less useful for invoking from other programs:

$ echo 'ping | jq ascii_upcase' | json-rpc-shell ws://localhost:1234
json-rpc> ping | jq ascii_upcase
"PONG"

Reporting bugs

Use https://git.janouch.name/p/json-rpc-shell to report bugs, request features, or submit pull requests.

See also

jq(1), readline(3) or editline(7)