1jc(1) JSON CLI output utility jc(1)
2
6 jc - JSONifies the output of many CLI tools and file-types
7
9 COMMAND | jc PARSER [OPTIONS]
10 or "Magic" syntax:
12 jc [OPTIONS] COMMAND
14
17 jc JSONifies the output of many CLI tools and file-types for easier
18 parsing in scripts. jc accepts piped input from STDIN and outputs a
19 JSON representation of the previous command's output to STDOUT. Alter‐
20 natively, the "Magic" syntax can be used by prepending jc to the com‐
21 mand to be converted. Options can be passed to jc immediately before
22 the command is given. (Note: "Magic" syntax does not support shell
23 builtins or command aliases)
24
27 Parsers:
28 --acpi `acpi` command parser
32 --airport
35 `airport -I` command parser
36 --airport-s
39 `airport -s` command parser
40 --arp `arp` command parser
43 --blkid
46 `blkid` command parser
47 --cksum
50 `cksum` and `sum` command parser
51 --crontab
54 `crontab` command and file parser
55 --crontab-u
58 `crontab` file parser with user support
59 --csv CSV file parser
62 --csv-s
65 CSV file streaming parser
66 --date `date` command parser
69 --df `df` command parser
72 --dig `dig` command parser
75 --dir `dir` command parser
78 --dmidecode
81 `dmidecode` command parser
82 --dpkg-l
85 `dpkg -l` command parser
86 --du `du` command parser
89 --env `env` command parser
92 --file `file` command parser
95 --finger
98 `finger` command parser
99 --free `free` command parser
102 --fstab
105 `/etc/fstab` file parser
106 --group
109 `/etc/group` file parser
110 --gshadow
113 `/etc/gshadow` file parser
114 --hash `hash` command parser
117 --hashsum
120 hashsum command parser (`md5sum`, `shasum`, etc.)
121 --hciconfig
124 `hciconfig` command parser
125 --history
128 `history` command parser
129 --hosts
132 `/etc/hosts` file parser
133 --id `id` command parser
136 --ifconfig
139 `ifconfig` command parser
140 --ini INI file parser
143 --iptables
146 `iptables` command parser
147 --iw-scan
150 `iw dev [device] scan` command parser
151 --jobs `jobs` command parser
154 --kv Key/Value file parser
157 --last `last` and `lastb` command parser
160 --ls `ls` command parser
163 --ls-s `ls` command streaming parser
166 --lsblk
169 `lsblk` command parser
170 --lsmod
173 `lsmod` command parser
174 --lsof `lsof` command parser
177 --lsusb
180 `lsusb` command parser
181 --mount
184 `mount` command parser
185 --netstat
188 `netstat` command parser
189 --ntpq `ntpq -p` command parser
192 --passwd
195 `/etc/passwd` file parser
196 --ping `ping` and `ping6` command parser
199 --ping-s
202 `ping` and `ping6` command streaming parser
203 --pip-list
206 `pip list` command parser
207 --pip-show
210 `pip show` command parser
211 --ps `ps` command parser
214 --route
217 `route` command parser
218 --rpm-qi
221 `rpm -qi` command parser
222 --sfdisk
225 `sfdisk` command parser
226 --shadow
229 `/etc/shadow` file parser
230 --ss `ss` command parser
233 --stat `stat` command parser
236 --sysctl
239 `sysctl` command parser
240 --systemctl
243 `systemctl` command parser
244 --systemctl-lj
247 `systemctl list-jobs` command parser
248 --systemctl-ls
251 `systemctl list-sockets` command parser
252 --systemctl-luf
255 `systemctl list-unit-files` command parser
256 --systeminfo
259 `systeminfo` command parser
260 --time `/usr/bin/time` command parser
263 --timedatectl
266 `timedatectl status` command parser
267 --tracepath
270 `tracepath` and `tracepath6` command parser
271 --traceroute
274 `traceroute` and `traceroute6` command parser
275 --ufw `ufw status` command parser
278 --ufw-appinfo
281 `ufw app info [application]` command parser
282 --uname
285 `uname -a` command parser
286 --upower
289 `upower` command parser
290 --uptime
293 `uptime` command parser
294 --vmstat
297 `vmstat` command parser
298 --vmstat-s
301 `vmstat` command streaming parser
302 --w `w` command parser
305 --wc `wc` command parser
308 --who `who` command parser
311 --xml XML file parser
314 --yaml YAML file parser
317 Options:
321 -a about jc (JSON output)
324 -d debug - show traceback (use -dd for verbose traceback)
326 -h help (-h --parser_name for parser documentation)
328 -m monochrome output
330 -p pretty print output
332 -q quiet - suppress warnings (use -qq to ignore streaming
334 parser errors)
335 -r raw JSON output
337 -u unbuffer output (useful for slow streaming data with
339 streaming parsers)
340 -v version information
342
345 Any fatal errors within jc will generate an exit code of 100, otherwise
346 the exit code will be 0. When using the "Magic" syntax (e.g. jc ifcon‐
347 fig eth0), jc will store the exit code of the program being parsed and
348 add it to the jc exit code. This way it is easier to determine if an
349 error was from the parsed program or jc.
350 Consider the following examples using `ifconfig`:
352 ifconfig exit code = 0, jc exit code = 0, combined exit code = 0
354 (no errors)
355 ifconfig exit code = 1, jc exit code = 0, combined exit code = 1
357 (error in ifconfig)
358 ifconfig exit code = 0, jc exit code = 100, combined exit code =
360 100 (error in jc)
361 ifconfig exit code = 1, jc exit code = 100, combined exit code =
363 101 (error in both ifconfig and jc)
364
367 You can specify custom colors via the JC_COLORS environment variable.
368 The JC_COLORS environment variable takes four comma separated string
369 values in the following format:
370 JC_COLORS=<keyname_color>,<keyword_color>,<number_color>,<string_color>
372 Where colors are: black, red, green, yellow, blue, magenta, cyan, gray,
374 brightblack, brightred, brightgreen, brightyellow, brightblue, bright‐
375 magenta, brightcyan, white, or default
376 For example, to set to the default colors:
378 JC_COLORS=blue,brightblack,magenta,green
380 or
382 JC_COLORS=default,default,default,default
384
388 Most parsers load all of the data from STDIN, parse it, then output the
389 entire JSON document serially. There are some streaming parsers (e.g.
390 ls-s and ping-s) that immediately start processing and outputing the
391 data line-by-line as JSON Lines (aka NDJSON) while it is being received
392 from STDIN. This can significantly reduce the amount of memory required
393 to parse large amounts of command output (e.g. ls -lR /) and can some‐
394 times process the data more quickly. Streaming parsers have slightly
395 different behavior than standard parsers as outlined below.
396 Note: Streaming parsers cannot be used with the "magic" syntax
398 Ignoring Errors
400 You may want to ignore parsing errors when using streaming parsers
402 since these may be used in long-lived processing pipelines and errors
403 can break the pipe. To ignore parsing errors, use the -qq cli option.
404 This will add a _jc_meta object to the JSON output with a success at‐
405 tribute. If success is true, then there were no issues parsing the
406 line. If success is false, then a parsing issue was found and error and
407 line fields will be added to include a short error description and the
408 contents of the unparsable line, respectively:
409 Successfully parsed line with -qq option:
411 {
412 "command_data": "data",
414 "_jc_meta": {
416 "success": true
418 }
420 }
422 Unsuccessfully parsed line with -qq option:
424 {
425 "_jc_meta": {
427 "success": false,
429 "error": "error message",
431 "line": "original line data"
433 }
435 }
437 Unbuffering Output
439 Most operating systems will buffer output that is being piped from
441 process to process. The buffer is usually around 4KB. When viewing the
442 output in the terminal the OS buffer is not engaged so output is imme‐
443 diately displayed on the screen. When piping multiple processes to‐
444 gether, though, it may seem as if the output is hanging when the input
445 data is very slow (e.g. ping):
446 $ ping 1.1.1.1 | jc --ping-s | jq
448 <slow output>
450 This is because the OS engages the 4KB buffer between jc and jq in this
452 example. To display the data on the terminal in realtime, you can dis‐
453 able the buffer with the -u (unbuffer) cli option:
454 $ ping 1.1.1.1 | jc --ping-s -u | jq
456 {"type":"reply","pattern":null,"time‐
458 stamp":null,"bytes":"64","re‐
459 sponse_ip":"1.1.1.1","icmp_seq":"1","ttl":"128","time_ms":"24.6","du‐
460 plicate":false}
461 {"type":"reply","pattern":null,"time‐
463 stamp":null,"bytes":"64","re‐
464 sponse_ip":"1.1.1.1","icmp_seq":"2","ttl":"128","time_ms":"26.8","du‐
465 plicate":false}
466 etc...
468 Note: Unbuffered output can be slower for large data streams.
470
473 Custom local parser plugins may be placed in a jc/jcparsers folder in
474 your local "App data directory":
475 - Linux/unix: $HOME/.local/share/jc/jcparsers
477 - macOS: $HOME/Library/Application Support/jc/jcparsers
479 - Windows: $LOCALAPPDATA\jc\jc\jcparsers
481 Local parser plugins are standard python module files. Use the
483 jc/parsers/foo.py parser as a template and simply place a .py file in
484 the jcparsers subfolder.
485 Local plugin filenames must be valid python module names, therefore
487 must consist entirely of alphanumerics and start with a letter. Local
488 plugins may override default plugins.
489 Note: The application data directory follows the XDG Base Directory
491 Specification
492
495 Locale: For best results set the LANG locale environment variable to C
496 or en_US.UTF-8. For example, either by setting directly on the command-
497 line:
498 $ LANG=C date | jc --date
500 or by exporting to the environment before running commands:
502 $ export LANG=C
504 Timezones: Some parsers have calculated epoch timestamp fields added to
506 the output. Unless a timestamp field name has a _utc suffix it is con‐
507 sidered naive. (i.e. based on the local timezone of the system the jc
508 parser was run on).
509 If a UTC timezone can be detected in the text of the command output,
511 the timestamp will be timezone aware and have a _utc suffix on the key
512 name. (e.g. epoch_utc) No other timezones are supported for aware time‐
513 stamps.
514
517 Standard Syntax:
518 $ dig www.google.com | jc --dig -p
519 Magic Syntax:
521 $ jc -p dig www.google.com
522 For parser documentation:
524 $ jc -h --dig
525
527 Kelly Brazil (kellyjonbrazil@gmail.com)
528 https://github.com/kellyjonbrazil/jc
530
533 Copyright (c) 2019-2021 Kelly Brazil
534 License: MIT License
5361.17.2 2021-11-18 jc(1)