Repository files navigation

pipeform is a TUI for Terraform runtime progress.

pipeform as its name indicates, shall be preceded byterraform run, through a pipe (|). Only the followingterraform commands are supported:

• terraform refresh -json
• terraform plan -json
• terraform apply -auto-approve -json

Note that all the commands must have the-json flag specified, as the tool is built on top of theTerraform machine-readable UI.

Example:

go install github.com/magodo/pipeform@main

The tool will generate a CSV file for further analysis/visualization by specifying the--time-csv=<path> option.

A taste of the output:

Start Timestamp,End Timestamp,Stage,Action,Module,Resource Type,Resource Name,Resource Key,Status,Duration (sec)1735018449,1735018453,apply,create,,null_resource,cluster,13,complete,41735018449,1735018453,apply,create,,null_resource,cluster,3,complete,41735018449,1735018451,apply,create,,null_resource,cluster,1,complete,21735018450,1735018451,apply,create,,null_resource,cluster,25,complete,11735018450,1735018452,apply,create,,null_resource,cluster,26,complete,2

By default,pipeform requires atty to make the UI work, which is unavailable in most CI systems (e.g. Github Actionhas no tty). To support this environment, the tool comes with an option--plain-ui, which will print out logs similar to theterraform default logs, except for the operations, it will prefix with a progress indicator.

Example.

In a successful run, the tool will end up at theSUMMARY stage, that displays a table of output variables defined. Users can select any of the output variables and pressc to copy the value to the system clipboard.

Note that the clipboard functionality is only enabled when the tool is built properly (CGO might be required) on a supported platform.Details.

When the tool ends in either successful or failed state, the user is supposed to quit. Then the tool will print the Terraform JSON warning/error diagnostics tostderr.

Especially, if Terraform encounters an error, the tool will display an error indicator ❌ in the "state" section on the top left and stay in the terminated state.

There are two ways to exit during operation:

• Terminatepipeform
• Terminateterraform

Though, it is highly recommendedNOT to terminate in the middle of the run.

There is a key bind for terminatingpipeform. When the user hit the key to quit,pipeform will quit immediately, which causes the pipe to close. Sinceterraform is still running and piping out logs, it will then hit aSIGPIPE signal, whichterraform has no special handling and defaults to terminateterraform immediately.

Terraform can be terminated by interruption (ctrl-c). It even hassome graceful handling for the interruption signal.

Whilst when usingpipeform, since the terminal is turned intoraw mode, pressingctrl-c won't send the signal at all. Instead, you'll have to send the signal manually.

Under Linux you can do something as below:

$ # Find out the ppid of the `pipeform`$ ps -ef | grep pipeformmagodo     88375    8823  1 11:05 pts/7    00:00:00 pipeformmagodo     89764   49424  0 11:05 pts/6    00:00:00 grep --color pipeform$ # 8823 is the ppid of `pipeform`$ # Use pstree to find the pid of the preceded `terraform`$ pstree -lpT 8823zsh(8823)─┬─pipeform(88375)          └─terraform(88374)───terraform-provi(88695)$ # 88374 is the pid of `terraform`$ # Send the signal manully$ kill -SIGINT 88374

Afterterraform being interrupted in the middle,pipeform won't just quit. Instead, it will respond to the diagnostics sent fromterraform (onceterraform finishes itsgraceful handling) and display the error indicators to users.

Windows Powershell (at up to 5.1.22621.4391) does not pipe byte-streams like UNIX shells or the DOS Command interpreter. The Powershell also faces the sameissue, until v7.4.0-preview.4 (with thisPR merged).

For users want to usepipeform under PowerShell, please ensure you have installed PowerShell newer than v7.4.0.

For users want to usepipeform under Windows Powershell, please invoke the DOS Command interpreter instead:cmd "/c terraform.exe <command> -json | pipeform.exe" (or just use the DOS Command interpreter instead).