1jc(1) JSON Convert jc(1)
2
6 jc - JSON Convert 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 --asciitable
46 ASCII and Unicode table parser
47 --asciitable-m
50 multi-line ASCII and Unicode table parser
51 --blkid
54 `blkid` command parser
55 --chage
58 `chage --list` command parser
59 --cksum
62 `cksum` and `sum` command parser
63 --crontab
66 `crontab` command and file parser
67 --crontab-u
70 `crontab` file parser with user support
71 --csv CSV file parser
74 --csv-s
77 CSV file streaming parser
78 --date `date` command parser
81 --df `df` command parser
84 --dig `dig` command parser
87 --dir `dir` command parser
90 --dmidecode
93 `dmidecode` command parser
94 --dpkg-l
97 `dpkg -l` command parser
98 --du `du` command parser
101 --env `env` command parser
104 --file `file` command parser
107 --finger
110 `finger` command parser
111 --free `free` command parser
114 --fstab
117 `/etc/fstab` file parser
118 --git-log
121 `git log` command parser
122 --git-log-s
125 `git log` command streaming parser
126 --gpg `gpg --with-colons` command parser
129 --group
132 `/etc/group` file parser
133 --gshadow
136 `/etc/gshadow` file parser
137 --hash `hash` command parser
140 --hashsum
143 hashsum command parser (`md5sum`, `shasum`, etc.)
144 --hciconfig
147 `hciconfig` command parser
148 --history
151 `history` command parser
152 --hosts
155 `/etc/hosts` file parser
156 --id `id` command parser
159 --ifconfig
162 `ifconfig` command parser
163 --ini INI file parser
166 --iostat
169 `iostat` command parser
170 --iostat-s
173 `iostat` command streaming parser
174 --iptables
177 `iptables` command parser
178 --iw-scan
181 `iw dev [device] scan` command parser
182 --jar-manifest
185 MANIFEST.MF file parser
186 --jobs `jobs` command parser
189 --kv Key/Value file parser
192 --last `last` and `lastb` command parser
195 --ls `ls` command parser
198 --ls-s `ls` command streaming parser
201 --lsblk
204 `lsblk` command parser
205 --lsmod
208 `lsmod` command parser
209 --lsof `lsof` command parser
212 --lsusb
215 `lsusb` command parser
216 --mount
219 `mount` command parser
220 --mpstat
223 `mpstat` command parser
224 --mpstat-s
227 `mpstat` command streaming parser
228 --netstat
231 `netstat` command parser
232 --nmcli
235 `nmcli` command parser
236 --ntpq `ntpq -p` command parser
239 --passwd
242 `/etc/passwd` file parser
243 --pidstat
246 `pidstat -h` command parser
247 --pidstat-s
250 `pidstat -h` command streaming parser
251 --ping `ping` and `ping6` command parser
254 --ping-s
257 `ping` and `ping6` command streaming parser
258 --pip-list
261 `pip list` command parser
262 --pip-show
265 `pip show` command parser
266 --postconf
269 `postconf -M` command parser
270 --ps `ps` command parser
273 --route
276 `route` command parser
277 --rpm-qi
280 `rpm -qi` command parser
281 --rsync
284 `rsync` command parser
285 --rsync-s
288 `rsync` command streaming parser
289 --sfdisk
292 `sfdisk` command parser
293 --shadow
296 `/etc/shadow` file parser
297 --ss `ss` command parser
300 --stat `stat` command parser
303 --stat-s
306 `stat` command streaming parser
307 --sysctl
310 `sysctl` command parser
311 --systemctl
314 `systemctl` command parser
315 --systemctl-lj
318 `systemctl list-jobs` command parser
319 --systemctl-ls
322 `systemctl list-sockets` command parser
323 --systemctl-luf
326 `systemctl list-unit-files` command parser
327 --systeminfo
330 `systeminfo` command parser
331 --time `/usr/bin/time` command parser
334 --timedatectl
337 `timedatectl status` command parser
338 --top `top -b` command parser
341 --top-s
344 `top -b` command streaming parser
345 --tracepath
348 `tracepath` and `tracepath6` command parser
349 --traceroute
352 `traceroute` and `traceroute6` command parser
353 --ufw `ufw status` command parser
356 --ufw-appinfo
359 `ufw app info [application]` command parser
360 --uname
363 `uname -a` command parser
364 --update-alt-gs
367 `update-alternatives --get-selections` command parser
368 --update-alt-q
371 `update-alternatives --query` command parser
372 --upower
375 `upower` command parser
376 --uptime
379 `uptime` command parser
380 --vmstat
383 `vmstat` command parser
384 --vmstat-s
387 `vmstat` command streaming parser
388 --w `w` command parser
391 --wc `wc` command parser
394 --who `who` command parser
397 --x509-cert
400 X.509 PEM and DER certificate file parser
401 --xml XML file parser
404 --xrandr
407 `xrandr` command parser
408 --yaml YAML file parser
411 --zipinfo
414 `zipinfo` command parser
415 Options:
419 -a, --about
422 About jc (JSON or YAML output)
423 -C, --force-color
425 Force color output even when using pipes (overrides -m
426 and the NO_COLOR env variable)
427 -d, --debug
429 Debug - show traceback (use -dd for verbose traceback)
430 -h, --help
432 Help (--help --parser_name for parser documentation)
433 -m, --monochrome
435 Monochrome output
436 -p, --pretty
438 Pretty print output
439 -q, --quiet
441 Quiet mode. Suppresses parser warning messages (use -qq
442 to ignore streaming parser errors)
443 -r, --raw
445 Raw output. Provides more literal output, typically with
446 string values and no additional semantic processing
447 -u, --unbuffer
449 Unbuffer output (useful for slow streaming data with
450 streaming parsers)
451 -v, --version
453 Version information
454 -y, --yaml-out
456 YAML output
457 -B, --bash-comp
459 Generate Bash shell completion script
460 -Z, --zsh-comp
462 Generate Zsh shell completion script
463
466 Any fatal errors within jc will generate an exit code of 100, otherwise
467 the exit code will be 0. When using the "Magic" syntax (e.g. jc ifcon‐
468 fig eth0), jc will store the exit code of the program being parsed and
469 add it to the jc exit code. This way it is easier to determine if an
470 error was from the parsed program or jc.
471 Consider the following examples using ifconfig:
473 ifconfig exit code = 0, jc exit code = 0, combined exit code = 0
475 (no errors)
476 ifconfig exit code = 1, jc exit code = 0, combined exit code = 1
478 (error in ifconfig)
479 ifconfig exit code = 0, jc exit code = 100, combined exit code =
481 100 (error in jc)
482 ifconfig exit code = 1, jc exit code = 100, combined exit code =
484 101 (error in both ifconfig and jc)
485
488 Custom Colors
489 You can specify custom colors via the JC_COLORS environment variable.
491 The JC_COLORS environment variable takes four comma separated string
492 values in the following format:
493 JC_COLORS=<keyname_color>,<keyword_color>,<number_color>,<string_color>
495 Where colors are: black, red, green, yellow, blue, magenta, cyan, gray,
497 brightblack, brightred, brightgreen, brightyellow, brightblue, bright‐
498 magenta, brightcyan, white, or default
499 For example, to set to the default colors:
501 JC_COLORS=blue,brightblack,magenta,green
503 or
505 JC_COLORS=default,default,default,default
507 Disable Color Output
509 You can set the NO_COLOR environment variable to any value to disable
511 color output in jc. Note that using the -C option to force color output
512 will override both the NO_COLOR environment variable and the -m option.
513
516 Most parsers load all of the data from STDIN, parse it, then output the
517 entire JSON document serially. There are some streaming parsers (e.g.
518 ls-s, ping-s, etc.) that immediately start processing and outputing the
519 data line-by-line as JSON Lines (aka NDJSON) while it is being received
520 from STDIN. This can significantly reduce the amount of memory required
521 to parse large amounts of command output (e.g. ls -lR /) and can some‐
522 times process the data more quickly. Streaming parsers have slightly
523 different behavior than standard parsers as outlined below.
524 Note: Streaming parsers cannot be used with the "magic" syntax
526 Ignoring Errors
528 You may want to ignore parsing errors when using streaming parsers
530 since these may be used in long-lived processing pipelines and errors
531 can break the pipe. To ignore parsing errors, use the -qq cli option.
532 This will add a _jc_meta object to the JSON output with a success at‐
533 tribute. If success is true, then there were no issues parsing the
534 line. If success is false, then a parsing issue was found and error and
535 line fields will be added to include a short error description and the
536 contents of the unparsable line, respectively:
537 Successfully parsed line with -qq option:
539 {
540 "command_data": "data",
541 "_jc_meta": {
542 "success": true
543 }
544 }
545 Unsuccessfully parsed line with -qq option:
547 {
548 "_jc_meta": {
549 "success": false,
550 "error": "error message",
551 "line": "original line data"
552 }
553 }
554 Unbuffering Output
556 Most operating systems will buffer output that is being piped from
558 process to process. The buffer is usually around 4KB. When viewing the
559 output in the terminal the OS buffer is not engaged so output is imme‐
560 diately displayed on the screen. When piping multiple processes to‐
561 gether, though, it may seem as if the output is hanging when the input
562 data is very slow (e.g. ping):
563 $ ping 1.1.1.1 | jc --ping-s | jq
565 <slow output>
566 This is because the OS engages the 4KB buffer between jc and jq in this
568 example. To display the data on the terminal in realtime, you can dis‐
569 able the buffer with the -u (unbuffer) cli option:
570 $ ping 1.1.1.1 | jc --ping-s -u | jq
572 {"type":"reply","pattern":null,"timestamp":null,"bytes":"64",...}
573 {"type":"reply","pattern":null,"timestamp":null,"bytes":"64",...}
574 etc...
575 Note: Unbuffered output can be slower for large data streams.
577
580 Custom local parser plugins may be placed in a jc/jcparsers folder in
581 your local "App data directory":
582 - Linux/unix: $HOME/.local/share/jc/jcparsers
584 - macOS: $HOME/Library/Application Support/jc/jcparsers
585 - Windows: $LOCALAPPDATA\jc\jc\jcparsers
586 Local parser plugins are standard python module files. Use the
588 jc/parsers/foo.py or jc/parsers/foo_s.py (streaming) parser as a tem‐
589 plate and simply place a .py file in the jcparsers subfolder.
590 Local plugin filenames must be valid python module names and therefore
592 must start with a letter and consist entirely of alphanumerics and un‐
593 derscores. Local plugins may override default parsers.
594 Note: The application data directory follows the XDG Base Directory
596 Specification
597
600 Locale
601 For best results set the LANG locale environment variable to C or
603 en_US.UTF-8. For example, either by setting directly on the command-
604 line:
605 $ LANG=C date | jc --date
607 or by exporting to the environment before running commands:
609 $ export LANG=C
611 On some older systems UTF-8 output will be downgraded to ASCII with \u
613 escape sequences if the C locale does not support UTF-8 encoding.
614 Timezones
616 Some parsers have calculated epoch timestamp fields added to the out‐
618 put. Unless a timestamp field name has a _utc suffix it is considered
619 naive. (i.e. based on the local timezone of the system the jc parser
620 was run on).
621 If a UTC timezone can be detected in the text of the command output,
623 the timestamp will be timezone aware and have a _utc suffix on the key
624 name. (e.g. epoch_utc) No other timezones are supported for aware time‐
625 stamps.
626
629 Standard Syntax:
630 $ dig www.google.com | jc --dig -p
631 Magic Syntax:
633 $ jc -p dig www.google.com
634 For parser documentation:
636 $ jc -h --dig
637
639 Kelly Brazil (kellyjonbrazil@gmail.com)
640 https://github.com/kellyjonbrazil/jc
642
645 Copyright (c) 2019-2022 Kelly Brazil
646 License: MIT License
6481.20.2 2022-07-05 jc(1)