CLI Reference

This page provides documentation for our command line tools.

terraform-ingest

Terraform Ingest - A terraform multi-repo module AI RAG ingestion engine.

This tool accepts a YAML file of terraform git repository sources, downloads them locally, and creates JSON summaries for RAG ingestion.

Usage:

terraform-ingest [OPTIONS] COMMAND [ARGS]...

Options:

  --version  Show the version and exit.
  --help     Show this message and exit.

analyze

Analyze a single terraform repository.

REPOSITORY_URL: Git URL of the repository to analyze.

Example:

terraform-ingest analyze https://github.com/user/terraform-module

terraform-ingest analyze https://github.com/user/terraform-module -b develop --include-tags

Usage:

terraform-ingest analyze [OPTIONS] REPOSITORY_URL

Options:

  -b, --branch TEXT             Branch to analyze
  -o, --output PATH             Output file for the summary (default: stdout)
  --include-tags / --no-tags    Include git tags in analysis
  --max-tags INTEGER            Maximum number of tags to process
  --recursive / --no-recursive  Recursively search for terraform modules in
                                subdirectories
  --help                        Show this message and exit.

config

Manage configuration file settings.

This command group provides tools to read and update configuration files. Use 'set' and 'get' for single values, and 'add-repo' or 'remove-repo' for managing repository entries.

Example:

terraform-ingest config set --target output_dir --value ./my-output

terraform-ingest config get --target clone_dir

terraform-ingest config add-repo --url https://github.com/org/repo

terraform-ingest config remove-repo --url https://github.com/org/repo

Usage:

terraform-ingest config [OPTIONS] COMMAND [ARGS]...

Options:

  --help  Show this message and exit.

add-repo

Add a repository to the configuration.

This command adds a new repository entry to the repositories array in the configuration file.

Example:

terraform-ingest config add-repo --url https://github.com/org/repo

terraform-ingest config add-repo --url https://github.com/org/repo --name my-repo --branches main,develop

terraform-ingest config add-repo --url https://github.com/org/repo --recursive --max-tags 5

Usage:

terraform-ingest config add-repo [OPTIONS]

Options:

  -c, --config PATH               Configuration file to update (default:
                                  config.yaml)
  --url TEXT                      Repository URL  [required]
  --name TEXT                     Repository name (optional)
  --branches TEXT                 Comma-separated list of branches to include
  --include-tags / --no-include-tags
                                  Include git tags in analysis
  --max-tags INTEGER              Maximum number of tags to include
  --path TEXT                     Base path for module scanning
  --recursive / --no-recursive    Recursively search for terraform modules
  --help                          Show this message and exit.

get

Get a configuration value or show entire configuration.

TARGET should be a dot-separated path to the configuration key. For nested values, use dots to separate levels (e.g., 'embedding.enabled'). If TARGET is not provided, the entire configuration is displayed.

Example:

terraform-ingest config get

terraform-ingest config get --target output_dir

terraform-ingest config get --target embedding.enabled

terraform-ingest config get --target mcp --json

terraform-ingest config get --json

Usage:

terraform-ingest config get [OPTIONS]

Options:

  -c, --config PATH  Configuration file to read (default: config.yaml)
  -t, --target TEXT  Configuration path to get (e.g., 'output_dir',
                     'embedding.enabled'). If not provided, shows entire
                     config.
  -j, --json         Output as JSON
  --help             Show this message and exit.

remove-repo

Remove a repository from the configuration.

Specify either --url or --name to identify the repository to remove.

Example:

terraform-ingest config remove-repo --url https://github.com/org/repo

terraform-ingest config remove-repo --name my-repo

Usage:

terraform-ingest config remove-repo [OPTIONS]

Options:

  -c, --config PATH  Configuration file to update (default: config.yaml)
  --url TEXT         Repository URL to remove
  --name TEXT        Repository name to remove
  --help             Show this message and exit.

set

Set a configuration value.

TARGET should be a dot-separated path to the configuration key. For nested values, use dots to separate levels (e.g., 'embedding.enabled').

VALUE will be automatically converted to the appropriate type: - 'true' or 'false' becomes boolean - Numeric strings become integers or floats - Everything else remains a string

Example:

terraform-ingest config set --target output_dir --value ./output

terraform-ingest config set --target embedding.enabled --value true

terraform-ingest config set --target mcp.port --value 3000

Usage:

terraform-ingest config set [OPTIONS]

Options:

  -c, --config PATH  Configuration file to update (default: config.yaml)
  -t, --target TEXT  Configuration path to set (e.g., 'output_dir',
                     'embedding.enabled')  [required]
  -v, --value TEXT   Value to set (use 'true'/'false' for booleans, numbers
                     for integers)  [required]
  --help             Show this message and exit.

function

Manage MCP functions and operations.

This group provides commands to interact with MCP (Model Context Protocol) functions, including showing available functions and executing them.

Example:

terraform-ingest function show

terraform-ingest function exec my-function --arg value

Usage:

terraform-ingest function [OPTIONS] COMMAND [ARGS]...

Options:

  --help  Show this message and exit.

exec

Execute an MCP function.

FUNCTION_NAME: Name of the function to execute.

This command executes a specific MCP function with the provided arguments and returns the results.

Example:

terraform-ingest function exec list_modules

terraform-ingest function exec search_modules -a query "aws vpc" -a provider "aws"

terraform-ingest function exec get_module_details -a repository "https://github.com/..." -a ref "main"

Usage:

terraform-ingest function exec [OPTIONS] FUNCTION_NAME

Options:

  -a, --arg TEXT...         Function arguments as key-value pairs (use
                            multiple times for multiple args)
  -o, --output-dir TEXT     Directory containing ingested module summaries
  -f, --format [json|text]  Output format for function results
  --help                    Show this message and exit.

show

Show available MCP functions and their details.

This command displays information about all available MCP functions that can be executed against ingested Terraform modules.

Example:

terraform-ingest function show

terraform-ingest function show --output-dir ./my-output --format json

Usage:

terraform-ingest function show [OPTIONS]

Options:

  -o, --output-dir TEXT           Directory containing ingested module
                                  summaries
  -f, --format [table|json|list]  Output format for function list
  --help                          Show this message and exit.

import

Import repositories from external sources into configuration.

This command group allows importing repositories from various sources (GitHub, GitLab, etc.) and updating your configuration file.

Example:

terraform-ingest import github --org hashicorp --config config.yaml

terraform-ingest import github --org myorg --terraform-only --replace

Usage:

terraform-ingest import [OPTIONS] COMMAND [ARGS]...

Options:

  --help  Show this message and exit.

github

Import repositories from a GitHub organization.

This command fetches all repositories from a GitHub organization and adds them to your configuration file. By default, it merges with existing repositories. Use --replace to override the existing list.

Example:

terraform-ingest import github --org hashicorp

terraform-ingest import github --org myorg --token ghp_xxx --terraform-only

terraform-ingest import github --org myorg --replace --config my-config.yaml

terraform-ingest import github --org myorg --max-tags 5 --branches main,develop

Usage:

terraform-ingest import github [OPTIONS]

Options:

  --org TEXT          GitHub organization name  [required]
  --token TEXT        GitHub personal access token (or set GITHUB_TOKEN env
                      var)
  -c, --config PATH   Configuration file to update (default: config.yaml)
  --include-private   Include private repositories (requires authentication)
  --terraform-only    Only include repositories that contain Terraform files
  --base-path TEXT    Base path for module scanning (default: .)
  --replace           Replace existing repositories instead of merging
  --max-tags INTEGER  Maximum number of tags to include per repository
                      (default: 1)
  --branches TEXT     Comma-separated list of branches to include (default:
                      empty)
  --help              Show this message and exit.

gitlab

Import repositories from a GitLab group.

This command fetches all repositories from a GitLab group (optionally including subgroups) and adds them to your configuration file. By default, it merges with existing repositories. Use --replace to override the existing list.

Example:

terraform-ingest import gitlab --group mygroup

terraform-ingest import gitlab --group mygroup --token glpat-xxx --terraform-only

terraform-ingest import gitlab --group mygroup --replace --config my-config.yaml

terraform-ingest import gitlab --group mygroup --max-tags 5 --branches main,develop

terraform-ingest import gitlab --group mygroup --recursive --gitlab-url https://gitlab.example.com

Usage:

terraform-ingest import gitlab [OPTIONS]

Options:

  --group TEXT                  GitLab group name or ID  [required]
  --token TEXT                  GitLab personal access token (or set
                                GITLAB_TOKEN env var)
  -c, --config PATH             Configuration file to update (default:
                                config.yaml)
  --include-private             Include private repositories (requires
                                authentication)
  --terraform-only              Only include repositories that contain
                                Terraform files
  --base-path TEXT              Base path for module scanning (default: .)
  --replace                     Replace existing repositories instead of
                                merging
  --max-tags INTEGER            Maximum number of tags to include per
                                repository (default: 1)
  --branches TEXT               Comma-separated list of branches to include
                                (default: empty)
  --recursive / --no-recursive  Recursively fetch repositories from subgroups
                                (default: true)
  --gitlab-url TEXT             GitLab instance URL (default:
                                https://gitlab.com)
  --help                        Show this message and exit.

index

Manage the module index for fast lookups.

Usage:

terraform-ingest index [OPTIONS] COMMAND [ARGS]...

Options:

  --help  Show this message and exit.

by-provider

Search modules by provider.

Usage:

terraform-ingest index by-provider [OPTIONS] PROVIDER

Options:

  --output-dir PATH  Output directory with module JSON files
  --json             Output as JSON
  --help             Show this message and exit.

by-tag

Search modules by tag.

Usage:

terraform-ingest index by-tag [OPTIONS] TAG

Options:

  --output-dir PATH  Output directory with module JSON files
  --json             Output as JSON
  --help             Show this message and exit.

get

Get full module summary by index ID.

Usage:

terraform-ingest index get [OPTIONS] DOC_ID

Options:

  --output-dir PATH  Output directory with module JSON files
  --json             Output as JSON
  --help             Show this message and exit.

lookup

Look up a module by its document ID.

Usage:

terraform-ingest index lookup [OPTIONS] DOC_ID

Options:

  --output-dir PATH  Output directory with module JSON files
  --json             Output as JSON
  --help             Show this message and exit.

rebuild

Rebuild the module index from all JSON files.

Usage:

terraform-ingest index rebuild [OPTIONS]

Options:

  --output-dir PATH  Output directory with module JSON files
  --help             Show this message and exit.

stats

Show module index statistics.

Usage:

terraform-ingest index stats [OPTIONS]

Options:

  --output-dir PATH  Output directory with module JSON files
  --help             Show this message and exit.

ingest

Ingest terraform repositories from a YAML configuration file.

CONFIG_FILE: Path to the YAML configuration file containing repository sources.

Example:

terraform-ingest ingest config.yaml

terraform-ingest ingest config.yaml -o ./my-output -c ./my-repos

terraform-ingest ingest config.yaml --enable-embeddings --embedding-strategy sentence-transformers

terraform-ingest ingest config.yaml --skip-existing

terraform-ingest ingest config.yaml --chromadb-path /custom/chromadb/path

Usage:

terraform-ingest ingest [OPTIONS] [CONFIG_FILE]

Options:

  -o, --output-dir TEXT           Directory to save JSON summaries
  -c, --clone-dir TEXT            Directory to clone repositories
  --cleanup / --no-cleanup        Clean up cloned repositories after ingestion
  --no-cache / --cache            Disable caching for module analysis
  --enable-embeddings / --no-embeddings
                                  Enable or disable vector database embeddings
                                  (overrides config)
  --embedding-strategy [openai|claude|sentence-transformers|chromadb-default]
                                  Embedding strategy to use (overrides config)
  --auto-install-deps / --no-auto-install-deps
                                  Automatically install missing embedding
                                  dependencies
  --skip-existing / --no-skip-existing
                                  Skip cloning if repository already exists in
                                  local cache
  -db, --chromadb-path TEXT       Path to ChromaDB storage directory
                                  (overrides config)
  --help                          Show this message and exit.

init

Initialize a sample configuration file.

CONFIG_FILE: Path where the configuration file should be created.

Example:

terraform-ingest init config.yaml

Usage:

terraform-ingest init [OPTIONS] CONFIG_FILE

Options:

  --help  Show this message and exit.

install-deps

Install optional dependencies for embedding strategies.

This command manages installation of packages needed for vector database and embedding functionality. It can read from a configuration file or use explicit strategy options.

If CONFIG_FILE is provided, dependencies will be installed based on the embedding configuration in that file. Otherwise, use --strategy to specify.

Example:

# From config file
terraform-ingest install-deps config.yaml

# Explicit strategy
terraform-ingest install-deps --strategy sentence-transformers

# All strategies
terraform-ingest install-deps --strategy all

# Report only (no install)
terraform-ingest install-deps config.yaml --no-auto-install

Usage:

terraform-ingest install-deps [OPTIONS] [CONFIG_FILE]

Options:

  --strategy [openai|claude|sentence-transformers|chromadb-default|all]
                                  Embedding strategy to install dependencies
                                  for (overrides config file)
  --no-auto-install / --auto-install
                                  Skip automatic installation (only report
                                  missing packages)
  --help                          Show this message and exit.

mcp

Start the MCP (Model Context Protocol) server.

The MCP server exposes ingested Terraform modules to AI agents and supports auto-ingestion based on configuration settings.

Supported transports: - stdio (default): Standard input/output communication - streamable-http: HTTP with streaming support - sse: Server-Sent Events over HTTP

Example:

terraform-ingest mcp

terraform-ingest mcp --config my-config.yaml

terraform-ingest mcp --ingest-on-startup

terraform-ingest mcp --transport streamable-http --host 0.0.0.0 --port 3000

terraform-ingest mcp --transport sse --host localhost --port 8000 --ingest-on-startup

Usage:

terraform-ingest mcp [OPTIONS]

Options:

  -c, --config TEXT               Configuration file for auto-ingestion
                                  settings
  -t, --transport [stdio|streamable-http|sse]
                                  Transport mode (stdio, streamable-http, or
                                  sse)
  -h, --host TEXT                 Host to bind to (for streamable-http and sse
                                  transports)
  -p, --port INTEGER              Port to bind to (for streamable-http and sse
                                  transports)
  --ingest-on-startup / --no-ingest-on-startup
                                  Run ingestion immediately on startup
                                  (overrides config)
  --help                          Show this message and exit.

module

Display ingested module data.

REPOSITORY: Repository name or URL identifier REF: Git reference (branch, tag, or commit)

Example:

terraform-ingest module terraform-aws-vpc v5.0.0

terraform-ingest module aws-s3 main --path ./modules/bucket

terraform-ingest module terraform-aws-vpc v5.0.0 --json

terraform-ingest module terraform-aws-vpc v5.0.0 -o /path/to/output

Usage:

terraform-ingest module [OPTIONS] REPOSITORY REF

Options:

  -p, --path TEXT        Module path within the repository (default: root)
  -j, --json             Output results in JSON format
  -o, --output-dir TEXT  Directory containing ingested JSON modules (default:
                         ./output)
  --help                 Show this message and exit.

resource

Retrieve and display an MCP resource by its path.

RESOURCE_PATH: MCP resource path in the format 'module://repository/ref/path'

This command retrieves a specific Terraform module resource and returns its JSON summary including variables, outputs, providers, and README.

Example:

terraform-ingest resource module://terraform-aws-vpc/v5.0.0

terraform-ingest resource module://terraform-aws-ec2/main

terraform-ingest resource module://terraform-aws-vpc/v5.0.0/modules-networking

Usage:

terraform-ingest resource [OPTIONS] RESOURCE_PATH

Options:

  -o, --output-dir TEXT  Directory containing ingested module summaries
  --help                 Show this message and exit.

search

Search the vector database for Terraform modules.

QUERY: Search query (natural language or keywords)

Example:

terraform-ingest search "vpc module for aws"

terraform-ingest search "kubernetes" --provider aws --limit 5

terraform-ingest search "vpc" --json

Usage:

terraform-ingest search [OPTIONS] QUERY

Options:

  -c, --config PATH      Configuration file with vector DB settings
  -p, --provider TEXT    Filter by provider
  -r, --repository TEXT  Filter by repository
  -l, --limit INTEGER    Number of results to return
  -j, --json             Output results in JSON format
  --help                 Show this message and exit.

serve

Start the FastAPI server.

Example:

terraform-ingest serve

terraform-ingest serve --host 127.0.0.1 --port 8080

Usage:

terraform-ingest serve [OPTIONS]

Options:

  --host TEXT         Host to bind the server to
  -p, --port INTEGER  Port to bind the server to
  --help              Show this message and exit.