Skip to main content

CommandLog and Macros

The CommandLog records every action taken in VisiData as a replayable sequence. Macros bind a sequence of commands to a single key. Together they turn repetitive data workflows into one-key operations.

Learning Focus

The essential pattern: work interactively → Shift+D to inspect → Ctrl+S to save .vdj → replay with --play. This turns any ad-hoc cleaning session into a repeatable pipeline.

Sample Data Used in This Lesson​

cat > ~/github/practice-folder/visidata/04-cleaning/01-dirty_orders.csv << 'EOF'
order_id,customer,status,amount
1001,Alice,active,250
1002,Bob,PENDING,150
1003,Carol,Active,400
1004,Dave,error,0
EOF

vd ~/github/practice-folder/visidata/04-cleaning/01-dirty_orders.csv

View the CommandLog​

VisiData records every command automatically. Access it at any time:

Shift+D

CommandLog appears — each row is one recorded command:

sheet              col     row  keystrokes  longname        input
01-dirty_orders   amount       %           type-float      
01-dirty_orders   status       gs          select-all      
01-dirty_orders   status       g*          search-replace  active<Tab>ACTIVE
KeyShows
Shift+DCommands for current sheet only
gDAll commands across all sheets in the session
zDCurrent sheet commands with parent-sheet commands removed

Replay Commands​

Inside the CommandLog:

x     # replay the command at the current row (re-apply one step)
gx    # replay the entire CommandLog from start
^C    # abort a running replay

Save the CommandLog to a File​

# Open CommandLog
Shift+D

# Save the workflow
Ctrl+S
# Enter: ~/github/practice-folder/visidata/04-cleaning/clean_orders.vdj

The .vdj file is newline-delimited JSON — human-readable:

{"sheet": "01-dirty_orders", "col": "amount", "keystrokes": "%", "input": ""}
{"sheet": "01-dirty_orders", "col": "status", "keystrokes": "g*", "input": "active\tACTIVE"}
{"sheet": "01-dirty_orders", "col": "", "keystrokes": "Ctrl+S", "input": "cleaned.csv"}

You can edit this file directly — change a column name, modify a regex, or add new steps.

Batch Replay (No UI)​

Replay a saved .vdj on a new source file without opening the TUI:

vd --play ~/github/practice-folder/visidata/04-cleaning/clean_orders.vdj \
   --batch ~/github/practice-folder/visidata/04-cleaning/01-dirty_orders.csv \
   -o /tmp/orders_cleaned.csv

Flags:

  • --play = path to .vdj CommandLog
  • --batch = run headlessly (no interactive UI)
  • -o = output file (format auto-detected from extension)

Slow Replay for Demos​

vd --play ~/github/practice-folder/visidata/04-cleaning/clean_orders.vdj \
   --replay-wait 1.5 \
   ~/github/practice-folder/visidata/04-cleaning/01-dirty_orders.csv

--replay-wait 1.5 pauses 1.5 seconds between each replayed command — audience can follow along.

Record a Macro​

Macros bind a sequence of keystrokes to a single key. They persist across sessions.

vd ~/github/practice-folder/visidata/04-cleaning/01-dirty_orders.csv

# Start recording a macro bound to the 'f' key
m f

# Perform the sequence:
Shift+F         # open frequency table on current column
q               # return to source sheet

# Stop recording
m f

Result — pressing f on any column now does: Shift+F → q (frequency table + return).

warning

Macros override existing keybindings. Test your chosen key first. Use gm to see all current macro bindings.

View and Delete Macros​

gm
# Opens Macro Index — shows: key, commands sequence

# Press d to delete selected macro
# Press q to close

Macros are saved to ~/.visidata/macros/ and load automatically on startup.

Complete CommandLog Workflow​

vd ~/github/practice-folder/visidata/04-cleaning/01-dirty_orders.csv

  1. Perform cleaning steps interactively
  2. Shift+D    →  view recorded CommandLog
  3. Ctrl+S     →  save as: clean_orders.vdj
  4. q          →  return to source sheet

Next run (new file):
  vd --play clean_orders.vdj --batch new_orders.csv -o cleaned.csv

Key Reference​

KeyAction
Shift+DOpen CommandLog for current sheet
gDOpen global CommandLog (all sheets)
zDOpen CommandLog (current sheet only, no parent commands)
xReplay command at current row
gxReplay entire CommandLog
^CAbort replay
Ctrl+SSave CommandLog to .vdj file
m keyStart/stop recording macro to key
gmOpen Macro Index

Hands-On Practice​

vd ~/github/practice-folder/visidata/04-cleaning/01-dirty_orders.csv

# 1. Perform two operations:
#    - Move to 'amount' → press % (float)
#    - Move to 'status' → gs → g* → PENDING<Tab>pending

# 2. Open CommandLog: Shift+D
# 3. Verify your two operations appear as rows
# 4. Press Ctrl+S → save as: /tmp/practice_workflow.vdj
# 5. Press q → return to source sheet

# 6. Create a frequency macro:
m f
Shift+F
q
m f

# 7. Test macro: move to 'status' column → press f
# 8. Verify: frequency table opens and returns

# 9. Batch replay:
# vd --play /tmp/practice_workflow.vdj --batch 01-dirty_orders.csv -o /tmp/out.csv

What's Next​