The Command Log

As you use VisiData, it generates a temporary log of every modifying command you’ve run. This “command log” can assist you with a few things:

  • Seeing what you’ve done during a VisiData session
  • Saving that history (so that you can use it later or share it with others)
  • Replaying those commands

This chapter walks you through each of these steps.

Viewing the command log

From anywhere within VisiData, you can press D to view the command log relevant to your current sheet. It ignores actions you may have taken outside of the current sheet’s direct lineage. Essentially, it answers the question: What steps did I take to get here?

Let’s start with a simple example, following these steps:

  • Initiate a fresh VisiData session with vd faa-wildlife-strikes.csv
  • Rename the sheet to strikes: Press Space to raise the type-a-command prompt, type rename-sheet, press Enter, and type strikes, and then press Enter again
  • Navigate to the AIRPORT column
  • Press F to generate a frequency sheet of the AIRPORT columns
  • Navigate to the sixth row, and press s to select it

You should see something like this:

  File  Edit  View  Column  Row  Data  Plot  System  Help     Ctrl+H for help menu                  
 AIRPORT            ↓count♯| percent%| histogram                                         ~        
 UNKNOWN              8424 |   11.47 | **************************************************         
 DENVER INTL AIRPORT  2756 |    3.75 | ****************                                           
 DALLAS/FORT WORTH …  2392 |    3.26 | **************                                             
 CHICAGO O'HARE INT…  1583 |    2.16 | *********                                                  
 JOHN F KENNEDY INTL  1302 |    1.77 | *******                                                    
MEMPHIS INTL       ║  1217 |    1.66 | *******                                                    
 SALT LAKE CITY INTL║  1179 |    1.61 | ******                                             ║        
 PHILADELPHIA INTL    1131 |    1.54 | ******                                                     
 ORLANDO INTL         1026 |    1.40 | ******                                                     
 SACRAMENTO INTL      1021 |    1.39 | ******                                                     
 LA GUARDIA ARPT       974 |    1.33 | *****                                                      
 CHARLOTTE/DOUGLAS …   960 |    1.31 | *****                                                      
 NEWARK LIBERTY INT…   917 |    1.25 | *****                                                      
 LOUISVILLE INTL AR…   841 |    1.15 | ****                                                       
 AUSTIN-BERGSTROM I…   817 |    1.11 | ****                                                       
 LOUIE ARMSTRONG NE…   809 |    1.10 | ****                                                       
 KANSAS CITY INTL      807 |    1.10 | ****                                                       
 HARTSFIELD - JACKS…   775 |    1.06 | ****                                                       
 GEORGE BUSH INTERC…   746 |    1.02 | ****                                                       
 DETROIT METRO WAYN…   734 |    1.00 | ****                                                       
 BALTIMORE/WASH INT…   691 |    0.94 | ****                                                       
2› strikes_AIRPORT_freq| selected 1217 rows | selected 1 bins     s   select-row      1512 bins  •1 

Now press D to open the command log for this sheet:

  File  Edit  View  Column  Row  Data  Plot  System  Help     Ctrl+H for help menu                  
 sheet              | col     | row            | longname     | input              | keystrokes | 
                   |        |               | open-file    | faa-wildlife-strik…| o          |   
 faa-wildlife-strik…|         |                | rename-sheet | strikes            |           | 
 strikes            | AIRPORT |                | freq-col     |                    | Shift+F    | 
 strikes_AIRPORT_fr…|         | キMEMPHIS INTL | select-row   |                    | s          | 
                                                                                                    
                                                                                                    
                                                                                                    
                                                                                                    
                                                                                                    
                                                                                                    
                                                                                                    
                                                                                                    
                                                                                                    
                                                                                                    
                                                                                                    
                                                                                                    
                                                                                                    
                                                                                                    
                                                                                                    
                                                                                                    
                                                                                                    
› strikes_AIRPORT_freq_cmdlog|                             Shift+D            4 logged commands  •0 

Two things you’ll see that you might not have expected:

  • The command to open faa-wildlife-strikes.csv appears in the log, with “longname” open-file. Passing filenames to VisiData on the command line is equivalent to opening them within the program via open-file or keyboard shortcut o.
  • Navigational commands do not appear in the command log. The reason: Navigating around a sheet doesn’t alter its contents. For the frequency sheet (freq-col) and row-selection (select-row) commands, VisiData has captured the necessary context via the log’s col and row columns.

Saving the command log

The command log behaves virtually the same as any other sheet in VisiData. That means you can sort, filter, and otherwise edit its rows, columns, and cells. That also means you can save just like you’d save any other sheet, with Control-s. Doing so with the example above should raise a prompt that looks like this:

  File  Edit  View  Column  Row  Data  Plot  System  Help     Ctrl+H for help menu                  
 sheet              | col     | row            | longname     | input              | keystrokes | 
                   |        |               | open-file    | faa-wildlife-strik…| o          |   
 faa-wildlife-strik…|         |                | rename-sheet | strikes            |           | 
 strikes            | AIRPORT |                | freq-col     |                    | Shift+F    | 
 strikes_AIRPORT_fr…|         | キMEMPHIS INTL | select-row   |                    | s          | 
                                                                                                    
                                                                                                    
                                                                                                    
                                                                                                    
                                                                                                    
                                                                                                    
                                                                                                    
                                                                                                    
                                                                                                    
                                                                                                    
                                                                                                    
                                                                                                    
                                                                                                    
                                                                                                    
                                                                                                    
                                                                                                    
                                                                                                    
save to: strikes_AIRPORT_freq_cmdlog.vd           Ctrl+S   save-sheet         4 logged commands  •0 

As you’ll see, VisiData suggests its own .vd file extension. That helps distinguish command logs from other files, but it’s not necessary. It’s just a tab-separated-values file, and you can save it with the .tsv extension if you prefer. For the sake of the subsequent steps in this tutorial, let’s save it as example-cmdlog.vd, in the same directory as faa-wildlife-strikes.csv.

Replaying the full command log

To fully replay the example-cmdlog.vd log we saved in the section above, run the following command from your computer’s terminal:

vd --play example-cmdlog.vd

Note that, this time, we don’t point VisiData to the dataset itself, since that information (the path to the dataset) is now specified within the command log. If the replay worked, you should see VisiData advance through each step (some more quickly than others), ultimately arriving at the result you previously obtained manually:

  File  Edit  View  Column  Row  Data  Plot  System  Help     Ctrl+H for help menu                  
 AIRPORT            ↓count♯| percent%| histogram                                         ~        
 UNKNOWN              8424 |   11.47 | **************************************************         
 DENVER INTL AIRPORT  2756 |    3.75 | ****************                                           
 DALLAS/FORT WORTH …  2392 |    3.26 | **************                                             
 CHICAGO O'HARE INT…  1583 |    2.16 | *********                                                  
 JOHN F KENNEDY INTL  1302 |    1.77 | *******                                                    
MEMPHIS INTL       ║  1217 |    1.66 | *******                                                    
 SALT LAKE CITY INTL║  1179 |    1.61 | ******                                             ║        
 PHILADELPHIA INTL    1131 |    1.54 | ******                                                     
 ORLANDO INTL         1026 |    1.40 | ******                                                     
 SACRAMENTO INTL      1021 |    1.39 | ******                                                     
 LA GUARDIA ARPT       974 |    1.33 | *****                                                      
 CHARLOTTE/DOUGLAS …   960 |    1.31 | *****                                                      
 NEWARK LIBERTY INT…   917 |    1.25 | *****                                                      
 LOUISVILLE INTL AR…   841 |    1.15 | ****                                                       
 AUSTIN-BERGSTROM I…   817 |    1.11 | ****                                                       
 LOUIE ARMSTRONG NE…   809 |    1.10 | ****                                                       
 KANSAS CITY INTL      807 |    1.10 | ****                                                       
 HARTSFIELD - JACKS…   775 |    1.06 | ****                                                       
 GEORGE BUSH INTERC…   746 |    1.02 | ****                                                       
 DETROIT METRO WAYN…   734 |    1.00 | ****                                                       
 BALTIMORE/WASH INT…   691 |    0.94 | ****                                                       
2› strikes_AIRPORT_freq| select current row | selected 1217 rows  s   select-row      1512 bins  •1 

You can adjust the replay behavior via various command line arguments, such as:

vd --play example-cmdlog.vd --replay-wait 2

… which will pause two seconds between each of the logged steps. And:

vd --play example-cmdlog.vd --batch --output cmdlog-results.csv

… which will replay the command log in “batch” mode (displaying status messages but not the full VisiData interface) and, when complete, will save the final sheet to cmdlog-results.csv.

Sharing command logs on GitHub

Command logs can help you demonstrate specific VisiData behavior to others, especially if that behavior involves more than a few steps. You’ll want to do this, for instance, when filing potential bug reports via VisiData’s GitHub repository. Some advice for doing so:

  • When attaching a command log to a GitHub issue or comment, you’ll need to change the file extension, since GitHub will reject fileames ending in .vd. The developers recommend appending .txt to the filename; in the example above, that would be example-cmdlog.vd.txt.
  • If replaying the command log requires a specific dataset, attach that dataset in the same message and aim to make it as simple as possible. Alternatively, you can use a dataset from VisiData’s sample_data directory (for instance, as done in this issue).