DOCSEARCHbyAlgolia
Submit Docs

Pluralith CLI

repository·main·Indexed 21 days ago

https://github.com/pluralith/pluralith-cli

A CLI tool for visualizing Terraform state and automating infrastructure documentation. It generates visual diagrams of resources, detects infrastructure drift, highlights changes in Terraform plans, and integrates with Infracost for cost visualization. Key commands include `graph` for diagram generation, `init` for project setup, and `strip` for removing secrets from state files.

Tokens
5.2K
Snippets
24
Records
28
Agent score
73%

What's inside pluralith-cli

  1. Key features of Pluralith

    main

    Pluralith provides several capabilities for managing and documenting infrastructure:

    • Infrastructure Diagrams: Generate visual maps of your resources using pluralith plan.
    • CI Automation: Automatically update documentation by running Pluralith within your CI workflows.
    • Change Highlighting: The diagrams can highlight the specific changes introduced in the latest Terraform plan.
    • Drift Detection: Detect and visualize infrastructure drift (differences between your actual state and your configuration).
    • Cost Visualization: View the estimated cost of your infrastructure directly within the diagrams via integration with Infracost.

  2. Get started with Pluralith CLI

    main

    Pluralith is a tool designed to visualize Terraform state and automate infrastructure documentation. To use the CLI, you must have access to the Pluralith UI and/or an API key, which can be obtained by signing up for the alpha at pluralith.com.

    You can set up Pluralith in two primary ways:

    1. Run Locally: For local development and immediate visualization.
    2. Run in CI: To automate infrastructure documentation as part of your continuous integration pipeline.

    Detailed setup guides are available in the official documentation.

    See official documentation for specific setup commands:
- https://docs.pluralith.com/docs/get-started/run-locally
- https://docs.pluralith.com/docs/get-started/run-in-ci

  3. Use the Pluralith CLI

    main

    Pluralith is a tool designed to visualize your Terraform state. It hooks directly into your Terraform installation to generate real-time infrastructure diagrams.

    To use the CLI, ensure you have Terraform installed, as Pluralith relies on your existing Terraform environment to draw up the diagrams.

  4. How the Pluralith CLI initializes

    main

    The Pluralith CLI follows a specific initialization sequence during startup to ensure the environment is ready for command execution. When the application starts, it performs the following steps:

    1. Instance Locking: Uses dblock.LockInstance.GenerateLock() to prevent concurrent executions from interfering with each other.
    2. State & Path Setup: Initializes the application state, generates necessary system paths, and creates required application directories via auxiliary.StateInstance.
    3. Authentication: Attempts to set the API key via auxiliary.StateInstance.SetAPIKey().
    4. Component Updates: Checks for and installs updates for the GraphModule using components.GraphModule(true).
    5. Environment Context: Detects CI environments, identifies the current git branch, checks for Infracost availability, and loads environment variables.

    Once initialization is complete, the CLI hands off control to the command execution engine via cmd.Execute().

  5. Configure Pluralith via config file or environment variables

    main

    Pluralith uses viper to manage configuration. It looks for a configuration file named .pluralith (without extension) in your home directory by default.

    Key configuration behaviors:

    • Config File Location: If no specific config file is provided via flags, it searches for .pluralith in the user's home directory.
    • Environment Variables: The CLI automatically reads environment variables that match your configuration keys (via viper.AutomaticEnv()).
    • Manual Config Path: While currently commented out in the source, the CLI is designed to support a --config flag to specify a custom configuration file path.

  6. Use the pluralith graph command instead of apply

    main

    The pluralith apply command is deprecated. To run terraform apply and visualize changes in Pluralith, you should use the pluralith graph command instead.

    # Deprecated command
pluralith apply

# Recommended replacement
pluralith graph

  7. Run `init` non-interactively for CI/CD

    main

    To initialize a project in a CI/CD pipeline where interactive prompts are not possible, provide all required credentials via flags and include the --no-inputs flag. This tells Pluralith to assume all necessary parameters are already provided.

    pluralith init \
  --api-key "YOUR_API_KEY" \
  --org-id "YOUR_ORG_ID" \
  --project-id "YOUR_PROJECT_ID" \
  --project-name "my-project" \
  --no-inputs

  8. Create an empty `pluralith.yml` config file

    main

    If you want to manually configure your project later, you can use the --empty flag with the init command to generate a blank pluralith.yml configuration file in your current directory without running the full initialization process.

    pluralith init --empty

  9. Generate infrastructure diagrams with `pluralith plan`

    main
    You can instantly create infrastructure diagrams by running the pluralith plan command in your terminal. This command analyzes your Terraform state to produce a visual representation of your infrastructure.
    pluralith plan

  10. Reference: `run` command flags

    main

    The following persistent flags are available to the run command and its subcommands (plan, apply, destroy). These flags control diagram metadata, export behavior, cost visibility, and Terraform variable passing.

    --title string		The title for your diagram, will be displayed in the PDF output
--version string		The diagram version, will be displayed in the PDF output
--out-dir string		The directory the diagram should be exported to
--file-name string	The name of the exported PDF
--post-apply bool	Determines whether this run is after an apply and should update the latest docs for this infrastructure project
--export-pdf bool	Determines whether a PDF export of the run Diagram is generated locally
--sync-to-backend bool	Determines whether a PDF export of your diagram is stored in your state backend alongside your Terraform state. (Currently supports azurerm, gcs and s3)
--show-changes bool	Determines whether the exported diagram highlights changes made in the latest Terraform plan or outputs a general diagram of the infrastructure
--show-drift bool	Determines whether the exported diagram highlights resource drift detected by Terraform
--show-costs bool	Determines whether the exported diagram includes cost information
--cost-mode string	Determines which costs are shown. Can be 'delta' or 'total' (default: "delta")
--cost-period string	Determines over which period costs are aggregated. Can be 'hour' or 'month' (default: "month")
--var-file stringArray	Path to a var file to pass to Terraform. Can be specified multiple times.
--var stringArray	A variable to pass to Terraform. Can be specified multiple times. (Format: --var='NAME=VALUE')
--plan-file string	Path to an execution plan binary file. If passed, this will skip a plan run under the hood.
--plan-file-json string	Path to an execution plan json file. If passed, this will skip a plan run under the hood.
--cost-usage-file string	Path to an infracost usage file to be used for the cost breakdown
--config-file string	Path to a specific Pluralith yaml config

  11. Reference: `init` command flags

    main

    The following flags are available for the init command. Using these flags allows you to bypass interactive user prompts, which is particularly useful for CI/CD environments.

    --api-key string
    Your Pluralith API key. Pass via flag to skip user prompt.
--org-id string
    Your Org Id (Can be found in your Pluralith dashboard). Pass via flag to skip user prompt and override pluralith.yml
--project-id string
    Your Project Id (If no project with passed Id exists, one gets created). Pass via flag to skip user prompt and override pluralith.yml
--project-name string
    Your Project name. Pass via flag to skip user prompt and override pluralith.yml
--empty
    Creates an empty pluralith.yml config file in the current directory
--no-inputs
    Run init assuming all necessary parameters are present (for CI)

  12. Reference: `graph` command flags

    main

    The following flags are available for the graph command to control diagram generation, Terraform execution, and cost reporting.

    ### Export & Local Mode
--local-only (bool): Diagram will not be pushed to the Pluralith Dashboard. Instead, a PDF export of the Diagram is generated locally
--title (string): The title for your diagram, will be displayed in the PDF output
--author (string): The author/creator of the diagram, will be displayed in the PDF output
--version (string): The diagram version, will be displayed in the PDF output
--out-dir (string): The directory the diagram should be exported to
--file-name (string): The name of the exported PDF

### Visualization Options
--show-changes (bool): Determines whether the exported diagram highlights changes made in the latest Terraform plan or outputs a general diagram of the infrastructure
--show-drift (bool): Determines whether the exported diagram highlights resource drift detected by Terraform
--show-costs (bool): Determines whether the exported diagram includes cost information

### Cost Configuration
--cost-mode (string): Determines which costs are shown. Can be 'delta' or 'total' (default: "delta")
--cost-period (string): Determines over which period costs are aggregated. Can be 'hour' or 'month' (default: "month")
--cost-usage-file (string): Path to an infracost usage file to be used for the cost breakdown

### Terraform Execution
--plan-file (string): Path to an execution plan binary file. If passed, this will skip a plan run under the hood.
--plan-file-json (string): Path to an execution plan json file. If passed, this will skip a plan run under the hood.
--var-file (string array): Path to a var file to pass to Terraform. Can be specified multiple times.
--var (string array): A variable to pass to Terraform. Can be specified multiple times. (Format: --var='NAME=VALUE')

### Configuration
--config-file (string): Path to a specific Pluralith yaml config