Skip to content

environment-variables.md

Latest commit

 

History

History
416 lines (282 loc) · 12.4 KB

environment-variables.md

File metadata and controls

416 lines (282 loc) · 12.4 KB
Raw

Environment Variables

StructKit supports environment variables to configure CLI arguments without requiring them to be specified on the command line. This is particularly useful for CI/CD pipelines, containerized environments, and automation workflows.

Overview

Environment variables allow you to set default values for CLI arguments. Command-line arguments always take precedence over environment variables, ensuring flexibility when needed.

High Priority Environment Variables

STRUCTKIT_GLOBAL_SYSTEM_PROMPT

Sets the global system prompt for OpenAI integration.

CLI Equivalent: --global-system-prompt / -p

Use Case: Typically a long or sensitive value that users want to set once. Avoids repeating the same prompt across multiple invocations. Ideal for CI/CD workflows and container initialization.

Example:

export STRUCTKIT_GLOBAL_SYSTEM_PROMPT="You are a helpful assistant for generating project structures."
structkit generate my-structure ./output

STRUCTKIT_INPUT_STORE

Sets the path to the input store for template variables.

CLI Equivalent: --input-store / -n

Default: /tmp/structkit/input.json

Use Case: Allows users to set a consistent default location for input data. Useful for workflows that need persistent input across multiple runs.

Example:

export STRUCTKIT_INPUT_STORE="/home/user/structkit-inputs/data.json"
structkit generate my-structure ./output

STRUCTKIT_BACKUP_PATH

Sets the default backup location for file backups.

CLI Equivalent: --backup / -b

Use Case: Set a default backup location project-wide or environment-wide. Saves typing in repetitive operations. Useful for ensuring backups go to a specific location (e.g., mounted volume in containers).

Example:

export STRUCTKIT_BACKUP_PATH="/backups/structkit"
structkit generate my-structure ./output

Medium Priority Environment Variables

STRUCTKIT_FILE_STRATEGY

Sets the default strategy for handling existing files.

CLI Equivalent: --file-strategy / -f

Valid Values: overwrite, skip, append, rename, backup

Default: overwrite

Use Case: Let users set a preferred default strategy. Could prevent accidental data loss if set to 'skip' or 'backup' by default.

Example:

export STRUCTKIT_FILE_STRATEGY="backup"
structkit generate my-structure ./output

STRUCTKIT_NON_INTERACTIVE

Enables or disables interactive mode for all commands.

CLI Equivalent: --non-interactive

Valid Values: true, 1, yes (case-insensitive) for enabled; any other value for disabled

Default: false

Use Case: Boolean flag useful for CI/CD pipelines. Could be set in environment and applied across all commands.

Example:

export STRUCTKIT_NON_INTERACTIVE=true
structkit generate my-structure ./output

STRUCTKIT_OUTPUT_MODE

Sets the default output mode for the generate command.

CLI Equivalent: --output / -o

Valid Values: console, file

Default: file

Use Case: Some users might prefer 'console' output by default. Useful for pipeline integration.

Example:

export STRUCTKIT_OUTPUT_MODE="console"
structkit generate my-structure ./output

Shared Environment Variables

STRUCTKIT_STRUCTURES_PATH

Sets the path to custom structure definitions.

CLI Equivalent: --structures-path / -s

Use Case: Allows specifying custom structures directory that applies across all commands (generate, list, info, generate-schema).

Example:

export STRUCTKIT_STRUCTURES_PATH="/home/user/my-structures"
structkit list
structkit generate my-custom-structure ./output

STRUCTKIT_LOG_LEVEL

Sets the logging level for all commands.

CLI Equivalent: Applied in main.py after parsing. When set to a non-empty value, it overrides --log and --debug.

Valid Values: DEBUG, INFO, WARNING, ERROR, CRITICAL (case-insensitive; unknown values fall back to INFO)

Default: unset, then --debug if present, otherwise --log (default INFO)

Use Case: Control verbosity of output for debugging or production deployments.

Example:

export STRUCTKIT_LOG_LEVEL="DEBUG"
structkit generate my-structure ./output

Hook Safety

STRUCTKIT_NO_HOOKS

Skip all pre-generation and post-generation hooks.

CLI Equivalent: --no-hooks

Valid Values: true, 1, yes (case-insensitive) enable skipping; any other value (including unset) leaves hooks enabled

Default: unset / false (hooks run, subject to confirmation and allowlist)

Example:

export STRUCTKIT_NO_HOOKS=true
structkit generate my-structure ./output

STRUCTKIT_HOOKS_ALLOWLIST

Path to a hooks allowlist file. When hooks are enabled and this is unset, generate still loads .struct-hooks-allowlist from the current working directory if that file exists.

CLI Equivalent: --hooks-allowlist

Default: unset (None); then .struct-hooks-allowlist in the current directory if present

Example:

export STRUCTKIT_HOOKS_ALLOWLIST=/path/to/allowlist.txt
structkit generate my-structure ./output

Network and HTTP

Used by GitHub raw-content fetching in ContentFetcher (prefer raw.githubusercontent.com, then git fallback).

STRUCTKIT_DENY_NETWORK

Skip HTTP attempts and use the git fallback directly. Only the string 1 enables this; true/yes are not recognized.

Default: unset (HTTP is attempted)

Example:

export STRUCTKIT_DENY_NETWORK=1
structkit generate my-structure ./output

STRUCTKIT_HTTP_TIMEOUT

HTTP timeout in seconds for raw GitHub fetches.

Default: 10

Example:

export STRUCTKIT_HTTP_TIMEOUT=30

STRUCTKIT_HTTP_RETRIES

Number of retries after the first HTTP attempt (total attempts = retries + 1).

Default: 2

Example:

export STRUCTKIT_HTTP_RETRIES=0

Named Sources

These configure the sources file and git cache. They are separate from the CLI user config at ~/.config/struct/config.yaml.

STRUCTKIT_SOURCES_CONFIG

Override the user-level named sources config path.

CLI Equivalent: structkit sources --config-path

Default: $XDG_CONFIG_HOME/structkit/sources.yaml if XDG_CONFIG_HOME is set, otherwise ~/.config/structkit/sources.yaml

Example:

export STRUCTKIT_SOURCES_CONFIG=~/team/structkit-sources.yaml
structkit sources list

STRUCTKIT_SOURCES_CACHE

Override the local cache directory used for git-backed sources.

Default: $XDG_CACHE_HOME/structkit/sources if XDG_CACHE_HOME is set, otherwise ~/.cache/structkit/sources

Example:

export STRUCTKIT_SOURCES_CACHE=~/cache/structkit-sources

Precedence Rules

For flags that use environment variables as argparse defaults (STRUCTKIT_STRUCTURES_PATH, STRUCTKIT_FILE_STRATEGY, STRUCTKIT_INPUT_STORE, STRUCTKIT_BACKUP_PATH, STRUCTKIT_GLOBAL_SYSTEM_PROMPT, STRUCTKIT_NON_INTERACTIVE, STRUCTKIT_OUTPUT_MODE, STRUCTKIT_NO_HOOKS, STRUCTKIT_HOOKS_ALLOWLIST):

  1. Explicit command-line flags
  2. Environment variable (argparse default)
  3. Layered config files (--config-file, then ~/.config/struct/config.yaml, then built-in defaults)

Because those env vars populate argparse defaults, they override values from config files unless you pass a different CLI flag.

Exception: STRUCTKIT_LOG_LEVEL is applied after parsing and overrides --log and --debug when set.

STRUCTKIT_DENY_NETWORK, STRUCTKIT_HTTP_TIMEOUT, STRUCTKIT_HTTP_RETRIES, STRUCTKIT_SOURCES_CONFIG, and STRUCTKIT_SOURCES_CACHE are read directly where they are used; they are not CLI-config layers.

Example:

# Set default via environment variable
export STRUCTKIT_FILE_STRATEGY="backup"

# Override with CLI argument
structkit generate --file-strategy skip my-structure ./output
# Uses 'skip', not 'backup'

# Use default from environment
structkit generate my-structure ./output
# Uses 'backup' from STRUCTKIT_FILE_STRATEGY

Layered CLI config (~/.config/struct/config.yaml and --config-file) sits below those argparse env-var defaults. See Configuration.

Docker and Containerization

Environment variables are particularly useful when running StructKit in containers:

Docker Example:

docker run \
  -e STRUCTKIT_STRUCTURES_PATH=/custom/structures \
  -e STRUCTKIT_NON_INTERACTIVE=true \
  -e STRUCTKIT_FILE_STRATEGY=backup \
  -v /custom/structures:/custom/structures \
  -v $(pwd):/workdir \
  ghcr.io/httpdss/structkit:main generate my-structure /workdir/output

Docker Compose Example:

version: '3'
services:
  structkit:
    image: ghcr.io/httpdss/structkit:main
    environment:
      STRUCTKIT_STRUCTURES_PATH: /custom/structures
      STRUCTKIT_NON_INTERACTIVE: "true"
      STRUCTKIT_FILE_STRATEGY: backup
      STRUCTKIT_LOG_LEVEL: DEBUG
    volumes:
      - /custom/structures:/custom/structures
      - ./output:/workdir
    command: generate my-structure /workdir/output

CI/CD Pipeline Integration

GitHub Actions - Basic Example

name: Generate Project Structure

on: [push, pull_request]

jobs:
  generate:
    runs-on: ubuntu-latest
    env:
      STRUCTKIT_NON_INTERACTIVE: "true"
      STRUCTKIT_BACKUP_PATH: /tmp/backups
      STRUCTKIT_FILE_STRATEGY: backup
    steps:
      - uses: actions/checkout@v3

      - name: Install StructKit
        run: pip install structkit

      - name: Generate structure
        run: structkit generate my-structure ./generated-project

      - name: Upload generated files
        uses: actions/upload-artifact@v3
        with:
          name: generated-project
          path: generated-project/

GitHub Actions - Advanced Example with Custom Structures

name: Generate with Custom Structures

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]

jobs:
  generate:
    runs-on: ubuntu-latest
    env:
      STRUCTKIT_NON_INTERACTIVE: "true"
      STRUCTKIT_LOG_LEVEL: DEBUG
      STRUCTKIT_OUTPUT_MODE: console
    steps:
      - uses: actions/checkout@v3

      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.11'

      - name: Install StructKit
        run: pip install structkit

      - name: Generate default structure
        run: structkit generate python-basic ./my-project

      - name: Generate with custom backup strategy
        env:
          STRUCTKIT_BACKUP_PATH: ./backups
          STRUCTKIT_FILE_STRATEGY: backup
        run: structkit generate terraform-module ./my-infrastructure

      - name: Create summary
        run: |
          echo "## Generated Structures" >> $GITHUB_STEP_SUMMARY
          echo "- Python project generated" >> $GITHUB_STEP_SUMMARY
          echo "- Terraform module generated" >> $GITHUB_STEP_SUMMARY

Best Practices

  1. Use Environment Variables for Defaults - Set environment variables for values that don't change frequently
  2. Override When Needed - Use CLI arguments for one-off changes or specific use cases
  3. Document Configuration - Document which environment variables are used in your project
  4. Sensitive Data - Store sensitive data (like API keys) in environment variables, not in configuration files
  5. Validation - Test environment variable configuration to ensure it works as expected

Troubleshooting

Environment variable not being picked up

  1. Verify the environment variable is set: echo $VARIABLE_NAME
  2. Ensure you're using the correct variable name (case-sensitive on Linux/macOS)
  3. If running in Docker, check that the environment variable is passed correctly with -e
  4. Restart your terminal or shell session after setting the variable

CLI argument not overriding environment variable

This should not happen - CLI arguments always take precedence. If you're experiencing this:

  1. Verify the CLI argument is correctly formatted
  2. Check that you're using the correct argument name (e.g., --file-strategy not --strategy)
  3. Ensure there are no spaces or special characters in the argument value

Boolean environment variables not working correctly

For STRUCTKIT_NON_INTERACTIVE and STRUCTKIT_NO_HOOKS, only true, 1, and yes (case-insensitive, e.g., "True", "TRUE", "YeS") are recognized as true values. All other values are treated as false, including:

  • "true " (with trailing space)
  • "on" or "enable"

STRUCTKIT_DENY_NETWORK is stricter: only the exact value 1 disables HTTP fetches.

Use one of the recognized values for reliable behavior.