gh-atxp-dev-claude-cloud/commands/configure-env-var.md

name, description

name	description
configure-env-var	Set an environment variable for your deployed agent

Sets an environment variable by writing it to .atxp/.env.production, which is included in deployments to cloud.atxp.ai.

Usage

/configure-env-var KEY VALUE

Replace KEY with your environment variable name and VALUE with its value.

Examples

Set API keys for external services:

/configure-env-var GOOGLE_ANALYTICS_API_KEY ya29.a0AfH6SMBx...
/configure-env-var GOOGLE_SEARCH_CONSOLE_KEY AIzaSyC...
/configure-env-var DATAFORSEO_API_KEY 12345678-1234-1234-1234-123456789abc

How it works

1. Creates .atxp/.env.production if it doesn't exist
2. Adds or updates the environment variable in KEY=VALUE format
3. Sets file permissions to 600 (owner read/write only)
4. The file will be included in your next /deploy
5. Your deployed agent can access these variables at runtime

Requirements

• Bash 3.2+ (default on macOS and most Linux distributions)
• Write access to current directory

Value Handling

• Empty values: Not allowed. Use /remove-env-var to delete variables.
• Values with spaces: Fully supported (e.g., "Hello World")
• Values with special characters: Supported including =, :, /, etc.
• Multiline values: Not supported. Use base64 encoding if needed.

Implementation

#!/bin/bash

# Parse arguments
if [ "$#" -lt 2 ]; then
    echo "Usage: /configure-env-var KEY VALUE"
    echo "Example: /configure-env-var API_KEY abc123"
    exit 1
fi

KEY="$1"
shift
VALUE="$*"

# Validate key format (alphanumeric and underscore only)
if ! echo "$KEY" | grep -qE '^[A-Za-z_][A-Za-z0-9_]*$'; then
    echo "Error: KEY must start with a letter or underscore and contain only alphanumeric characters and underscores"
    exit 1
fi

# Create .atxp directory if it doesn't exist
mkdir -p .atxp

ENV_FILE=".atxp/.env.production"

# Create or update the env file
if [ -f "$ENV_FILE" ]; then
    # File exists, check if key already exists
    if grep -q "^${KEY}=" "$ENV_FILE"; then
        # Update existing key
        # Use a temporary file for safety
        TEMP_FILE=$(mktemp) || {
            echo "Error: Failed to create temporary file"
            exit 1
        }
        while IFS= read -r line; do
            if [[ "$line" =~ ^${KEY}= ]]; then
                echo "${KEY}=${VALUE}"
            else
                echo "$line"
            fi
        done < "$ENV_FILE" > "$TEMP_FILE"
        mv "$TEMP_FILE" "$ENV_FILE"
        echo "✓ Updated ${KEY} in ${ENV_FILE}"
    else
        # Append new key
        echo "${KEY}=${VALUE}" >> "$ENV_FILE"
        echo "✓ Added ${KEY} to ${ENV_FILE}"
    fi
else
    # Create new file
    echo "${KEY}=${VALUE}" > "$ENV_FILE"
    chmod 600 "$ENV_FILE"
    echo "✓ Created ${ENV_FILE} with ${KEY}"
fi

# Ensure restrictive permissions on existing file
chmod 600 "$ENV_FILE" 2>/dev/null || true

# Check if .gitignore exists and contains the env file
GITIGNORE_WARNED=false
if [ -f ".gitignore" ]; then
    if ! grep -qF ".atxp/.env.production" .gitignore; then
        GITIGNORE_WARNED=true
    fi
else
    GITIGNORE_WARNED=true
fi

if [ "$GITIGNORE_WARNED" = true ]; then
    echo ""
    echo "⚠️  SECURITY WARNING: Add .atxp/.env.production to your .gitignore"
    echo "   Run: echo '.atxp/.env.production' >> .gitignore"
fi

echo ""
echo "Next steps:"
echo "  1. Review variables: /list-env-vars"
echo "  2. Deploy your agent: /deploy"

Security Considerations

⚠️ Important Security Notes:

1. Git Protection: The .atxp/.env.production file contains sensitive credentials and should never be committed to version control. Add it to your .gitignore:

   echo '.atxp/.env.production' >> .gitignore
   

   The command will warn you if this entry is missing.

2. Shell History: When using this command, secrets are stored in your shell history. For highly sensitive values, consider:

   • Manually editing .atxp/.env.production instead
   • Clearing your shell history after use: history -d $(history 1)
   • Using environment variables: /configure-env-var API_KEY "$SECRET_FROM_ENV"

3. File Permissions: The file is automatically created with 600 permissions (owner read/write only) to prevent other system users from accessing secrets.

File Format

Variables are stored in standard .env format:

KEY1=value1
KEY2=value2
KEY3=value with spaces

Notes

• To update an existing variable, simply run the command again with the new value
• To view all configured variables, use /list-env-vars
• To remove a variable, use /remove-env-var KEY
• You can also manually edit .atxp/.env.production if needed
• Changes take effect on the next /deploy

Related Commands

• /list-env-vars - List all configured environment variables
• /remove-env-var - Remove an environment variable
• /deploy - Deploy your agent with environment variables