tushell

Environment Management in Tushell

This document covers the environment management system in Tushell CLI, which allows users to switch between different configurations using environment files.

Overview

The Tushell CLI supports loading environment variables from different .env files using the --env parameter. This enables users to manage multiple configurations and switch between them easily without modifying their system environment variables.

Environment File Loading Sequence

When running Tushell commands, environment variables are loaded in the following sequence:

  1. System environment variables
  2. Variables from .env file in the current directory (if it exists)
  3. Variables from $HOME/.env (if it exists)
  4. Variables from the file specified with --env parameter (if provided)

Each step can override variables set in the previous steps, with the --env parameter having the highest priority.

Implementation Details

The environment loading is implemented in the main cli() function in tushellcli.py:

@click.group()
@click.option('--env', '-E', default=None, help='Path to an alternative environment file to load')
def cli(env):
    """Main CLI group with optional environment file loading."""
    if env:
        # Load environment variables from the specified file
        if os.path.exists(env):
            load_dotenv(env, override=True)  # Use override=True to ensure variables are updated
            
            # Store the environment file path as an environment variable
            os.environ["TUSHELL_ENV_FILE"] = env
            
            click.echo(f"Loaded environment variables from {env}")
        else:
            click.echo(f"Error: Environment file {env} not found.")
            sys.exit(1)

Key Environment Variables

The following environment variables are particularly important for Tushell functionality:

Variable Description
EH_API_URL The API URL for communicating with the Echo Horizon service
EH_TOKEN Authentication token for API calls
EH_ENV_NAME Optional name for the environment (displayed in command output)
TUSHELL_ENV_FILE Set automatically when --env is used to track which file was loaded

Using Different Environment Files

To use a specific environment file:

tushell --env /path/to/your/file.env command [options]

For example:

tushell --env .env.production scan-keys --pattern "*resonance*"

Environment File Format

Environment files follow the standard .env format:

# Example .env.production file
EH_API_URL=https://production-api.example.com
EH_TOKEN=your_production_token
EH_ENV_NAME=Production

Environment Name Display

Commands like scan-keys display which environment they’re using. The display name is determined in this order of precedence:

  1. The value of EH_ENV_NAME if set
  2. The file path from TUSHELL_ENV_FILE if the --env parameter was used
  3. “default environment” as a fallback

For example:

$ tushell --env .env.production scan-keys

Loaded environment variables from .env.production

🔑 Scanning keys using Production environment 🔑

Debug Information

You can view information about the current environment with the --debug flag:

$ tushell --env .env.production scan-keys --debug

This will display:

Best Practices

  1. Naming Convention: Use .env.purpose naming pattern (e.g., .env.development, .env.staging, .env.production)
  2. Security: Never commit .env files containing sensitive tokens to version control
  3. Documentation: Maintain a .env.example file with placeholder values to document required variables
  4. Consistency: Use the same variable names across different environment files
  5. Custom Names: Set EH_ENV_NAME to a descriptive name for each environment to make it clear which one is active

Environment-Aware Commands

All commands in Tushell that interact with external services (like scan-keys, get-memory, etc.) are environment-aware. They fetch the environment variables at runtime rather than caching them at module level, ensuring they always use the most recently loaded values.

This design ensures that when you switch environments with --env, all commands will correctly use the new environment settings.

Troubleshooting

If you encounter issues with environment variables not being recognized:

  1. Use the --debug flag to see which variables are being loaded
  2. Check that your environment file exists and has the correct permissions
  3. Verify that variables are correctly formatted (no spaces around = sign)
  4. Remember that variables loaded with --env override those in the system environment

See Also