The CLI that looks at JSON in pretty
Tags: rust, opensource, tooling, json
Published: 2021-09-07 12:51:49

## What I made

[![tv](https://socialify.git.ci/uzimaru0000/tv/image?description=1&font=Raleway&language=1&owner=1&pattern=Circuit%20Board&stargazers=1&theme=Light)](https://github.com/uzimaru0000/tv)

This is a CLI for formatting JSON into a list for easy viewing.
I named it **TV** from **T**able **V**iew because I want to display it as a table.

## How to install

For Mac users, you can use homebrew to install it.

```bash
$ brew install tv
```

If you have Cargo, you can also install it using `cargo install`.
Note that it is `tv-cli`, not `tv`.


```bash
$ cargo install tv-cli
```

For other OS, you can download it from the GitHub [release](https://github.com/uzimaru0000/tv/releases/latest) page.

## How to use

Since `tv` was created as a minimal CLI, it only provides the ability to display tables and the associated options.

- Display JSON as an array in a table
- Specify a key and sort by that key
- Display the table in several styles

These are the main functions.

### Table View

As a use case, we will assume an API that returns JSON.
As an example of an API, we will use [jsonplaceholder](https://jsonplaceholder.typicode.com).
In this case, we will use https://jsonplaceholder.typicode.com/users.
This API will return the following data.

```
$ curl -s https://jsonplaceholder.typicode.com/users
[
  {
    "id": 1,
    "name": "Leanne Graham",
    "username": "Bret",
    "email": "Sincere@april.biz",
    "address": {
      "street": "Kulas Light",
      "suite": "Apt. 556",
      "city": "Gwenborough",
      "zipcode": "92998-3874",
      "geo": {
        "lat": "-37.3159",
        "lng": "81.1496"
      }
    },
    "phone": "1-770-736-8031 x56442",
    "website": "hildegard.org",
    "company": {
      "name": "Romaguera-Crona",
      "catchPhrase": "Multi-layered client-server neural-net",
      "bs": "harness real-time e-markets"
    }
  },
  ...
]
```

To display this data in an easy to read table view, we will use a pipe to enter it into `tv`.

```
$ curl -s https://jsonplaceholder.typicode.com/users | tv
+--+------------------------+----------------+-------------------------+-------+---------------------+-------------+-------+
|id|name                    |username        |email                    |address|phone                |website      |company|
+--+------------------------+----------------+-------------------------+-------+---------------------+-------------+-------+
|1 |Leanne Graham           |Bret            |Sincere@april.biz        |...    |1-770-736-8031 x56442|hildegard.org|...    |
|2 |Ervin Howell            |Antonette       |Shanna@melissa.tv        |...    |010-692-6593 x09125  |anastasia.net|...    |
|3 |Clementine Bauch        |Samantha        |Nathan@yesenia.net       |...    |1-463-123-4447       |ramiro.info  |...    |
|4 |Patricia Lebsack        |Karianne        |Julianne.OConner@kory.org|...    |493-170-9623 x156    |kale.biz     |...    |
|5 |Chelsey Dietrich        |Kamren          |Lucio_Hettinger@annie.ca |...    |(254)954-1289        |demarco.info |...    |
|6 |Mrs. Dennis Schulist    |Leopoldo_Corkery|Karley_Dach@jasper.info  |...    |1-477-935-8478 x6430 |ola.org      |...    |
|7 |Kurtis Weissnat         |Elwyn.Skiles    |Telly.Hoeger@billy.biz   |...    |210.067.6132         |elvis.io     |...    |
|8 |Nicholas Runolfsdottir V|Maxime_Nienow   |Sherwood@rosamond.me     |...    |586.493.6943 x140    |jacynthe.com |...    |
|9 |Glenna Reichert         |Delphine        |Chaim_McDermott@dana.io  |...    |(775)976-6794 x41206 |conrad.com   |...    |
|10|Clementina DuBuque      |Moriah.Stanton  |Rey.Padberg@karina.biz   |...    |024-648-3804         |ambrose.net  |...    |
+--+------------------------+----------------+-------------------------+-------+---------------------+-------------+-------+
```

As you can see, we were able to convert it into an easy-to-read table view.
If you have a large number of elements, you can use the less command to make it even easier to read.
If you already have the json file, you can also use it by entering path as an argument to the command.

```
$ tv data.json
```

### Change the style

`tv` has a number of `--style` options for changing the style.
The options are as follows

- ascii
  - default
- sharp
- rounded
- markdown
  - Table view in markdown
- plane
  - Ruled lines are not displayed

Use the display style of your choice.

###### `--style rounded` is applied
```
$ curl -s https://jsonplaceholder.typicode.com/users | tv --style --rounded
╭──┬────────────────────────┬────────────────┬─────────────────────────┬───────┬─────────────────────┬─────────────┬───────╮
│id│name                    │username        │email                    │address│phone                │website      │company│
├──┼────────────────────────┼────────────────┼─────────────────────────┼───────┼─────────────────────┼─────────────┼───────┤
│1 │Leanne Graham           │Bret            │Sincere@april.biz        │...    │1-770-736-8031 x56442│hildegard.org│...    │
│2 │Ervin Howell            │Antonette       │Shanna@melissa.tv        │...    │010-692-6593 x09125  │anastasia.net│...    │
│3 │Clementine Bauch        │Samantha        │Nathan@yesenia.net       │...    │1-463-123-4447       │ramiro.info  │...    │
│4 │Patricia Lebsack        │Karianne        │Julianne.OConner@kory.org│...    │493-170-9623 x156    │kale.biz     │...    │
│5 │Chelsey Dietrich        │Kamren          │Lucio_Hettinger@annie.ca │...    │(254)954-1289        │demarco.info │...    │
│6 │Mrs. Dennis Schulist    │Leopoldo_Corkery│Karley_Dach@jasper.info  │...    │1-477-935-8478 x6430 │ola.org      │...    │
│7 │Kurtis Weissnat         │Elwyn.Skiles    │Telly.Hoeger@billy.biz   │...    │210.067.6132         │elvis.io     │...    │
│8 │Nicholas Runolfsdottir V│Maxime_Nienow   │Sherwood@rosamond.me     │...    │586.493.6943 x140    │jacynthe.com │...    │
│9 │Glenna Reichert         │Delphine        │Chaim_McDermott@dana.io  │...    │(775)976-6794 x41206 │conrad.com   │...    │
│10│Clementina DuBuque      │Moriah.Stanton  │Rey.Padberg@karina.biz   │...    │024-648-3804         │ambrose.net  │...    │
╰──┴────────────────────────┴────────────────┴─────────────────────────┴───────┴─────────────────────┴─────────────┴───────╯
```

### Do not display the header

By default, the key name is displayed, but in some cases it may not be needed.
The `--no-headers` option can be used to turn off the display.

```
$ curl -s https://jsonplaceholder.typicode.com/users | tv --no-headers
+--+------------------------+----------------+-------------------------+-------+---------------------+-------------+-------+
|1 |Leanne Graham           |Bret            |Sincere@april.biz        |...    |1-770-736-8031 x56442|hildegard.org|...    |
|2 |Ervin Howell            |Antonette       |Shanna@melissa.tv        |...    |010-692-6593 x09125  |anastasia.net|...    |
|3 |Clementine Bauch        |Samantha        |Nathan@yesenia.net       |...    |1-463-123-4447       |ramiro.info  |...    |
|4 |Patricia Lebsack        |Karianne        |Julianne.OConner@kory.org|...    |493-170-9623 x156    |kale.biz     |...    |
|5 |Chelsey Dietrich        |Kamren          |Lucio_Hettinger@annie.ca |...    |(254)954-1289        |demarco.info |...    |
|6 |Mrs. Dennis Schulist    |Leopoldo_Corkery|Karley_Dach@jasper.info  |...    |1-477-935-8478 x6430 |ola.org      |...    |
|7 |Kurtis Weissnat         |Elwyn.Skiles    |Telly.Hoeger@billy.biz   |...    |210.067.6132         |elvis.io     |...    |
|8 |Nicholas Runolfsdottir V|Maxime_Nienow   |Sherwood@rosamond.me     |...    |586.493.6943 x140    |jacynthe.com |...    |
|9 |Glenna Reichert         |Delphine        |Chaim_McDermott@dana.io  |...    |(775)976-6794 x41206 |conrad.com   |...    |
|10|Clementina DuBuque      |Moriah.Stanton  |Rey.Padberg@karina.biz   |...    |024-648-3804         |ambrose.net  |...    |
+--+------------------------+----------------+-------------------------+-------+---------------------+-------------+-------+
```

### Display nested fields as well

By default, only primitive values are shown, and the rest are displayed with `...` .
In this case, it is preferable to `jq` the fields you want to display and pass them to `tv`, but there is also an option to display all nested fields.
There is also an option to display all nested fields, using the `-r` and `--recursive` options.

```
$ curl -s https://jsonplaceholder.typicode.com/users | tv -r
+--+------------------------+----------------+-------------------------+-------+---------------------+-------------+-------+
|id|name                    |username        |email                    |address|phone                |website      |company|
+--+------------------------+----------------+-------------------------+-------+---------------------+-------------+-------+
|1 |Leanne Graham           |Bret            |Sincere@april.biz        |...    |1-770-736-8031 x56442|hildegard.org|...    |
|2 |Ervin Howell            |Antonette       |Shanna@melissa.tv        |...    |010-692-6593 x09125  |anastasia.net|...    |
|3 |Clementine Bauch        |Samantha        |Nathan@yesenia.net       |...    |1-463-123-4447       |ramiro.info  |...    |
|4 |Patricia Lebsack        |Karianne        |Julianne.OConner@kory.org|...    |493-170-9623 x156    |kale.biz     |...    |
|5 |Chelsey Dietrich        |Kamren          |Lucio_Hettinger@annie.ca |...    |(254)954-1289        |demarco.info |...    |
|6 |Mrs. Dennis Schulist    |Leopoldo_Corkery|Karley_Dach@jasper.info  |...    |1-477-935-8478 x6430 |ola.org      |...    |
|7 |Kurtis Weissnat         |Elwyn.Skiles    |Telly.Hoeger@billy.biz   |...    |210.067.6132         |elvis.io     |...    |
|8 |Nicholas Runolfsdottir V|Maxime_Nienow   |Sherwood@rosamond.me     |...    |586.493.6943 x140    |jacynthe.com |...    |
|9 |Glenna Reichert         |Delphine        |Chaim_McDermott@dana.io  |...    |(775)976-6794 x41206 |conrad.com   |...    |
|10|Clementina DuBuque      |Moriah.Stanton  |Rey.Padberg@karina.biz   |...    |024-648-3804         |ambrose.net  |...    |
+--+------------------------+----------------+-------------------------+-------+---------------------+-------------+-------+

# company
+------------------+----------------------------------------+------------------------------------+
|name              |catchPhrase                             |bs                                  |
+------------------+----------------------------------------+------------------------------------+
|Romaguera-Crona   |Multi-layered client-server neural-net  |harness real-time e-markets         |
|Deckow-Crist      |Proactive didactic contingency          |synergize scalable supply-chains    |
|Romaguera-Jacobson|Face to face bifurcated interface       |e-enable strategic applications     |
|Robel-Corkery     |Multi-tiered zero tolerance productivity|transition cutting-edge web services|
|Keebler LLC       |User-centric fault-tolerant solution    |revolutionize end-to-end systems    |
|Considine-Lockman |Synchronised bottom-line interface      |e-enable innovative applications    |
|Johns Group       |Configurable multimedia task-force      |generate enterprise e-tailers       |
|Abernathy Group   |Implemented secondary concept           |e-enable extensible e-tailers       |
|Yost and Sons     |Switchable contextually-based project   |aggregate real-time technologies    |
|Hoeger LLC        |Centralized empowering task-force       |target end-to-end models            |
+------------------+----------------------------------------+------------------------------------+

# address
+-----------------+---------+--------------+----------+---+
|street           |suite    |city          |zipcode   |geo|
+-----------------+---------+--------------+----------+---+
|Kulas Light      |Apt. 556 |Gwenborough   |92998-3874|...|
|Victor Plains    |Suite 879|Wisokyburgh   |90566-7771|...|
|Douglas Extension|Suite 847|McKenziehaven |59590-4157|...|
|Hoeger Mall      |Apt. 692 |South Elvis   |53919-4257|...|
|Skiles Walks     |Suite 351|Roscoeview    |33263     |...|
|Norberto Crossing|Apt. 950 |South Christy |23505-1337|...|
|Rex Trail        |Suite 280|Howemouth     |58804-1099|...|
|Ellsworth Summit |Suite 729|Aliyaview     |45169     |...|
|Dayna Park       |Suite 449|Bartholomebury|76495-3109|...|
|Kattie Turnpike  |Suite 198|Lebsackbury   |31428-2261|...|
+-----------------+---------+--------------+----------+---+

# geo
+--------+---------+
|lat     |lng      |
+--------+---------+
|-37.3159|81.1496  |
|-43.9509|-34.4618 |
|-68.6102|-47.0653 |
|29.4572 |-164.2990|
|-31.8129|62.5342  |
|-71.4197|71.7478  |
|24.8918 |21.8984  |
|-14.3990|-120.7677|
|24.6463 |-168.8889|
|-38.2386|57.2232  |
+--------+---------+
```

### Sort by any field

You can sort the table by the value of any field.
Passing a field name to the `-s, --sort` option will sort the table by that value.

```
$ curl -s https://jsonplaceholder.typicode.com/users | tv -s username
+--+------------------------+----------------+-------------------------+-------+---------------------+-------------+-------+
|id|name                    |username        |email                    |address|phone                |website      |company|
+--+------------------------+----------------+-------------------------+-------+---------------------+-------------+-------+
|2 |Ervin Howell            |Antonette       |Shanna@melissa.tv        |...    |010-692-6593 x09125  |anastasia.net|...    |
|1 |Leanne Graham           |Bret            |Sincere@april.biz        |...    |1-770-736-8031 x56442|hildegard.org|...    |
|9 |Glenna Reichert         |Delphine        |Chaim_McDermott@dana.io  |...    |(775)976-6794 x41206 |conrad.com   |...    |
|7 |Kurtis Weissnat         |Elwyn.Skiles    |Telly.Hoeger@billy.biz   |...    |210.067.6132         |elvis.io     |...    |
|5 |Chelsey Dietrich        |Kamren          |Lucio_Hettinger@annie.ca |...    |(254)954-1289        |demarco.info |...    |
|4 |Patricia Lebsack        |Karianne        |Julianne.OConner@kory.org|...    |493-170-9623 x156    |kale.biz     |...    |
|6 |Mrs. Dennis Schulist    |Leopoldo_Corkery|Karley_Dach@jasper.info  |...    |1-477-935-8478 x6430 |ola.org      |...    |
|8 |Nicholas Runolfsdottir V|Maxime_Nienow   |Sherwood@rosamond.me     |...    |586.493.6943 x140    |jacynthe.com |...    |
|10|Clementina DuBuque      |Moriah.Stanton  |Rey.Padberg@karina.biz   |...    |024-648-3804         |ambrose.net  |...    |
|3 |Clementine Bauch        |Samantha        |Nathan@yesenia.net       |...    |1-463-123-4447       |ramiro.info  |...    |
+--+------------------------+----------------+-------------------------+-------+---------------------+-------------+-------+
```

### Specify the position to align the cells

By default, it is left-aligned, but you can use the `-a` and `--align` options to specify the alignment position.
The three possible values are as follows

- left
- center
- right

```
$ curl -s https://jsonplaceholder.typicode.com/users | tv -a center
+--+------------------------+----------------+-------------------------+-------+---------------------+-------------+-------+
|id|          name          |    username    |          email          |address|        phone        |   website   |company|
+--+------------------------+----------------+-------------------------+-------+---------------------+-------------+-------+
| 1|      Leanne Graham     |      Bret      |    Sincere@april.biz    |  ...  |1-770-736-8031 x56442|hildegard.org|  ...  |
| 2|      Ervin Howell      |    Antonette   |    Shanna@melissa.tv    |  ...  | 010-692-6593 x09125 |anastasia.net|  ...  |
| 3|    Clementine Bauch    |    Samantha    |    Nathan@yesenia.net   |  ...  |    1-463-123-4447   | ramiro.info |  ...  |
| 4|    Patricia Lebsack    |    Karianne    |Julianne.OConner@kory.org|  ...  |  493-170-9623 x156  |   kale.biz  |  ...  |
| 5|    Chelsey Dietrich    |     Kamren     | Lucio_Hettinger@annie.ca|  ...  |    (254)954-1289    | demarco.info|  ...  |
| 6|  Mrs. Dennis Schulist  |Leopoldo_Corkery| Karley_Dach@jasper.info |  ...  | 1-477-935-8478 x6430|   ola.org   |  ...  |
| 7|     Kurtis Weissnat    |  Elwyn.Skiles  |  Telly.Hoeger@billy.biz |  ...  |     210.067.6132    |   elvis.io  |  ...  |
| 8|Nicholas Runolfsdottir V|  Maxime_Nienow |   Sherwood@rosamond.me  |  ...  |  586.493.6943 x140  | jacynthe.com|  ...  |
| 9|     Glenna Reichert    |    Delphine    | Chaim_McDermott@dana.io |  ...  | (775)976-6794 x41206|  conrad.com |  ...  |
|10|   Clementina DuBuque   | Moriah.Stanton |  Rey.Padberg@karina.biz |  ...  |     024-648-3804    | ambrose.net |  ...  |
+--+------------------------+----------------+-------------------------+-------+---------------------+-------------+-------+
```

## Finally

I think it's useful for checking APIs returned in JSON, so please try it!
If you find any bugs while using it, please report them in the [issue](https://github.com/uzimaru0000/tv/issues).
If there is a feature you would like to see, please leave a comment in the [discussion](https://github.com/uzimaru0000/tv/discussions/26).