Run Command

Run Pluralith in CI, generate a diagram and post it as a pull request comment. pluralith run is primarly for usage in CI and usually preceeded by pluralith init.

tip

The pluralith run command is intended for use in CI. Check out how to get Pluralith set up in CI here.

pluralith run [command] [flags]

The pluralith run command supports two major modes: Plan and Apply & Destroy.

Plan

Run plan to get an overview of which changes will happen to your infrastructure. The diagrams generated here are based on terraform plan and, therefore, speculative. This is especially useful for pull request comments, as it gives everybody involved a clear overview of propsed changes to your infrastructure at an eye's glance.

pluralith run plan

Apply & Destroy

Run apply or destroy to deploy all the changes made since the last deployment. Here Pluralith serves as a thin wrapper around terraform apply|destroy and tracks all the apply events as they happen to enrich diagrams with information on what happened during deployment. The diagrams generated here don't just reflect planned changes, but actual changes applied to your infrastructure. They serve as a living piece of documentation that is always in sync with your deployed infrastructure.

pluralith run apply

pluralith run destroy

info

Why do we wrap Terraform?

Wrapping Terraform lets Pluralith do something really interesting: resource lifecycle management.

When terraform apply is run with its -json flag it outputs a precise, machine-readable set of events that contain lots of useful data, specifically information on when exactly a resource has been deployed or updated, errors that happened during deployment and similar. By wrapping terraform apply -json and processing these events we can provide you with a Cloud Asset Inventory that always updates when your IaC does. We can track a resource's entire lifecycle and show you when resources were created, all the updates that ever happened to them and (if given) when they were destroyed. If applicable, we also run Infracost and give you a history of a resource's costs over its entire lifecycle.

As pluralith run apply|destroy runs we also pipe the regular terraform output that you're used to to the console, so you always see what's up directly in your logs as well. This is a new part of the product that we are still actively exploring. We'd love your input, so if you have any ideas, questions or thoughts shoot us an email at dan@pluralith.com or phi@pluralith.com!

Example

Here's a quick example on how to run Pluralith in CI. First make sure to navigate to the directory that holds your Terraform project. Inside the Terraform project simply initialize Pluralith with pluralith init and your api-key, org-id and project-id. Then run pluralith run with any of the flags outlined below. After your pipeline run is done you should see a fresh run inside the Pluralith dashboard.

pluralith init --api-key $PLURALITH_API_KEY --org-id $PLURALITH_ORG_ID --project-id $PLURALITH_PROJECT_ID --project-name $PLURALITH_PROJECT_NAME
pluralith run plan

info

See details on pluralith init here to learn about the various ways you can pass the necessary config to the init command.

Available Flags

Flag	Description	Type
--show-changes	Determines whether the exported diagram highlights changes made in the latest Terraform plan	bool
--show-drift	Determines whether the exported diagram highlights resource drift detected by Terraform	bool
--show-costs	Determines whether the exported diagram includes cost information (requires Infracost)	bool
--cost-mode	Determines which costs are shown. Can be delta or total (default delta)	string
--cost-period	Determines over which period costs are aggregated. Can be hour or month (default month)	string
--cost-usage-file	Path to an infracost usage file to be used for the cost breakdown	string
--sync-to-backend	Determines whether a PDF export of your diagram is stored in your state backend alongside your Terraform state. (Currently supports azurerm, gcs and s3)	bool
--export-pdf	Determines whether a PDF export of the run is generated locally	bool
--file-name	The name of the exported PDF (Only relevant when --export-pdf is true)	string
--out-dir	The directory the diagram should be exported to (Only relevant when --export-pdf is true)	string
--title	The title for your diagram, will be displayed in the PDF output (Only relevant when --export-pdf is true)	string
--version	The diagram version, will be displayed in the PDF output (Only relevant when --export-pdf is true)	string
--var	A variable to pass to Terraform. Can be specified multiple times. (Format: --var='NAME=VALUE')	string
--var-file	Path to a variable file to pass to Terraform. Can be specified multiple times.	string
--plan-file	Path to an existing execution plan. (Generated with terraform plan -out plan.bin)	string
--plan-file-json	Path to an existing JSON plan state. (Generated with terraform plan -out plan.bin and terraform show -json plan.bin > plan.json)	string
--config-file	Path to a custom pluralith config file	string