1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
|
json-rpc-shell(1)
=================
:doctype: manpage
:manmanual: json-rpc-shell Manual
:mansource: json-rpc-shell {release-version}
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 server's response will be parsed and validated, stripping it
of the protocol's 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 isn't 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.
Environment
-----------
*VISUAL*, *EDITOR*::
The editor program to be launched by the M-e key binding.
If neither variable is set, it defaults to *vi*(1).
Files
-----
*json-rpc-shell* follows the XDG Base Directory Specification.
_~/.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 doesn't say almost anything about underlying
transports. The way it's implemented here is that every request is sent as
a single text message. If it has an "id" field, i.e., it's 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 may exhibit some unexpected behaviour.
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)
Specifications
~~~~~~~~~~~~~~
https://www.jsonrpc.org/specification +
https://www.json.org
|
