Skip to main content

Environment Commands

ReqSmith's environment system allows you to manage different configurations for various stages of development (development, staging, production) with environment-specific settings, variables, and authentication.

Environment Basics​

Listing Environments​

View available environments:

# List all environments
reqsmith env list

# List with details
reqsmith env list --details

# Show only active environment
reqsmith env list --active

# List environments with variables
reqsmith env list --show-variables

# Filter by pattern
reqsmith env list --filter "prod*"

Current Environment​

Check and manage current environment:

# Show current environment
reqsmith env current

# Show current environment details
reqsmith env show

# Show environment with resolved variables
reqsmith env show --resolve-variables

# Show environment configuration
reqsmith env show --config

Switching Environments​

Change active environment:

# Switch to specific environment
reqsmith env switch production

# Switch with confirmation
reqsmith env switch production --confirm

# Switch temporarily for single command
reqsmith env use staging -- reqsmith get /api/users

# Switch back to previous environment
reqsmith env switch -

# Set default environment
reqsmith env set-default production

Creating Environments​

Interactive Creation​

Create environments interactively:

# Create new environment interactively
reqsmith env create

# Create with basic information
reqsmith env create development \
  --description "Development environment" \
  --base-url https://dev-api.example.com

# Create from template
reqsmith env create staging --template production

# Create from current environment
reqsmith env create backup --from-current

File-based Creation​

Create environments from configuration files:

# Create from YAML file
reqsmith env create-from-file environment.yaml

# Create from JSON file
reqsmith env create-from-file environment.json

# Create from .env file
reqsmith env create-from-env .env.production --name production

# Import multiple environments
reqsmith env import-dir ./environments/

Environment Templates​

Use and create environment templates:

# List available templates
reqsmith env templates

# Create environment from template
reqsmith env create production --template cloud-api

# Create custom template
reqsmith env create-template \
  --name rest-api-template \
  --base-url "{{API_BASE_URL}}" \
  --auth-type bearer

# Save current environment as template
reqsmith env save-as-template current-env --name my-template

Environment Configuration​

Base Configuration​

Configure basic environment settings:

# Set base URL
reqsmith env set base_url https://api.example.com

# Set description
reqsmith env set description "Production API environment"

# Set timeout
reqsmith env set timeout 30000

# Set retry configuration
reqsmith env set retry_attempts 3
reqsmith env set retry_delay 1000

Headers and Authentication​

Configure environment-specific headers and auth:

# Set default headers
reqsmith env set-header User-Agent "MyApp/1.0"
reqsmith env set-header Accept "application/json"

# Set authentication
reqsmith env set-auth bearer "${API_TOKEN}"
reqsmith env set-auth api-key "X-API-Key" "${API_KEY}"
reqsmith env set-auth basic "username:password"

# Remove headers or auth
reqsmith env unset-header User-Agent
reqsmith env unset-auth

Variables​

Manage environment variables:

# Set environment variable
reqsmith env set-var API_VERSION v2
reqsmith env set-var USER_ID 12345

# Set from environment variable
reqsmith env set-var API_TOKEN "${PROD_API_TOKEN}"

# Import variables from file
reqsmith env import-vars variables.json

# Export variables to file
reqsmith env export-vars --output production-vars.json

# List all variables
reqsmith env vars

# Remove variable
reqsmith env unset-var API_VERSION

Environment Files​

YAML Configuration​

Create environment configuration in YAML:

# environments/production.yaml
name: production
description: Production API environment
base_url: https://api.example.com

variables:
  api_version: v2
  timeout: 30000
  user_id: 12345

headers:
  User-Agent: MyApp/1.0
  Accept: application/json
  X-Environment: production

authentication:
  type: bearer
  token: "${PROD_API_TOKEN}"

network:
  timeout: 30000
  retry_attempts: 3
  retry_delay: 1000
  verify_ssl: true

cache:
  enabled: true
  ttl: 3600

JSON Configuration​

Environments can also be defined in JSON:

{
  "name": "development",
  "description": "Development environment",
  "base_url": "https://dev-api.example.com",
  "variables": {
    "api_version": "v1",
    "debug": true
  },
  "headers": {
    "X-Environment": "development",
    "X-Debug": "true"
  },
  "authentication": {
    "type": "api_key",
    "header": "X-API-Key",
    "value": "${DEV_API_KEY}"
  }
}

Environment Files (.env)​

Use traditional .env files:

# .env.production
API_BASE_URL=https://api.example.com
API_TOKEN=prod-token-12345
API_VERSION=v2
TIMEOUT=30000
DEBUG=false

# .env.development
API_BASE_URL=https://dev-api.example.com
API_TOKEN=dev-token-67890
API_VERSION=v1
TIMEOUT=10000
DEBUG=true

Load .env files into environments:

# Load .env file into environment
reqsmith env load-env .env.production --env production

# Create environment from .env file
reqsmith env create-from-env .env.staging --name staging

# Auto-load .env files
reqsmith env auto-load-env --pattern ".env.*"

Environment Operations​

Copying and Cloning​

Copy environments and settings:

# Clone environment
reqsmith env clone production staging

# Copy specific settings
reqsmith env copy production staging --settings auth,headers

# Copy variables only
reqsmith env copy production staging --variables-only

# Copy with modifications
reqsmith env copy production staging \
  --set base_url=https://staging-api.example.com

Merging Environments​

Combine environment configurations:

# Merge environments
reqsmith env merge base-config production --output merged-env

# Merge with precedence
reqsmith env merge defaults production --precedence production

# Merge specific sections
reqsmith env merge base production --sections variables,headers

Environment Validation​

Validate environment configurations:

# Validate environment
reqsmith env validate production

# Validate all environments
reqsmith env validate-all

# Check for missing variables
reqsmith env check-variables production

# Test environment connectivity
reqsmith env test production

# Validate against schema
reqsmith env validate production --schema env-schema.json

Environment Security​

Credential Management​

Securely manage environment credentials:

# Store credentials securely
reqsmith env set-credential production api_token --encrypt

# Use credential vault
reqsmith env use-vault production --vault-name prod-vault

# Set credential from file
reqsmith env set-credential production cert --from-file cert.pem

# Remove credentials
reqsmith env remove-credential production api_token

# List stored credentials
reqsmith env list-credentials production

Environment Isolation​

Ensure environment isolation:

# Enable strict environment isolation
reqsmith env configure --strict-isolation

# Prevent cross-environment variable access
reqsmith env configure --isolate-variables

# Require confirmation for production
reqsmith env configure production --require-confirmation

# Set environment access permissions
reqsmith env set-permissions production --read-only

Sensitive Data Protection​

Protect sensitive information:

# Mark variables as sensitive
reqsmith env mark-sensitive production API_TOKEN

# Encrypt environment data
reqsmith env encrypt production --password-file password.txt

# Decrypt environment data
reqsmith env decrypt production --password-file password.txt

# Audit environment access
reqsmith env audit production --output audit.log

Environment Sharing​

Export and Import​

Share environments between team members:

# Export environment
reqsmith env export production --output production.yaml

# Export without sensitive data
reqsmith env export production --sanitize --output production-public.yaml

# Import environment
reqsmith env import production.yaml

# Import with name override
reqsmith env import staging.yaml --name new-staging

# Bulk import
reqsmith env import-batch ./team-environments/

Environment Packages​

Create and share environment packages:

# Create environment package
reqsmith env package production \
  --include-templates \
  --include-docs \
  --output production-package.zip

# Install environment package
reqsmith env install-package production-package.zip

# List package contents
reqsmith env package-info production-package.zip

# Update from package
reqsmith env update-from-package production production-package.zip

Team Environments​

Manage team environment configurations:

# Share environment with team
reqsmith env share production --team api-team

# Sync with team environment
reqsmith env sync production --from-team

# Create team template
reqsmith env create-team-template \
  --name api-template \
  --environments production,staging,development

# Apply team standards
reqsmith env apply-standards --template team-standards

Environment Automation​

Environment Scripts​

Automate environment operations:

# Run environment setup script
reqsmith env run-script production setup.sh

# Execute environment hooks
reqsmith env run-hooks production pre-deploy

# Automated environment tests
reqsmith env test-suite production --suite api-tests

# Environment health checks
reqsmith env health-check production --schedule "*/5 * * * *"

CI/CD Integration​

Use environments in CI/CD pipelines:

# Load environment in CI
reqsmith env load-from-ci --provider github-actions

# Export for CI
reqsmith env export-for-ci production --format env-vars

# Validate in CI pipeline
reqsmith env ci-validate --all --fail-on-error

# Deploy-specific environment
reqsmith env deploy-config production --target k8s

Environment Promotion​

Promote configurations between environments:

# Promote from staging to production
reqsmith env promote staging production

# Promote specific changes
reqsmith env promote staging production --changes api_version,timeout

# Promote with approval
reqsmith env promote staging production --require-approval

# Rollback promotion
reqsmith env rollback production --to-version 1.2.3

Advanced Environment Features​

Environment Hierarchies​

Create environment hierarchies:

# Set parent environment
reqsmith env set-parent staging production

# Show environment hierarchy
reqsmith env hierarchy

# Inherit from parent
reqsmith env inherit-from-parent staging --settings auth,headers

# Override parent settings
reqsmith env override staging base_url https://staging-api.example.com

Dynamic Environments​

Create dynamic environment configurations:

# Create dynamic environment
reqsmith env create-dynamic \
  --name feature-branch \
  --base production \
  --override base_url="https://{{BRANCH_NAME}}-api.example.com"

# Environment from template with variables
reqsmith env instantiate api-template \
  --name review-app \
  --var BRANCH_NAME=feature-123

# Temporary environment
reqsmith env create-temp \
  --base staging \
  --ttl 3600 \
  --name temp-test

Environment Monitoring​

Monitor environment usage and health:

# Monitor environment usage
reqsmith env monitor production --metrics requests,errors,latency

# Set up alerts
reqsmith env alert production \
  --condition "error_rate > 5%" \
  --notification email:admin@example.com

# Environment analytics
reqsmith env analytics production --period 7d

# Generate environment report
reqsmith env report production --output production-report.html

Command Reference​

Core Environment Commands​

# Environment management
reqsmith env list                     # List environments
reqsmith env show [NAME]              # Show environment details
reqsmith env current                  # Show current environment
reqsmith env switch NAME              # Switch to environment

# Environment creation
reqsmith env create NAME              # Create new environment
reqsmith env clone SOURCE TARGET      # Clone environment
reqsmith env import FILE              # Import environment

# Environment configuration
reqsmith env set KEY VALUE            # Set configuration
reqsmith env set-var KEY VALUE        # Set variable
reqsmith env set-header NAME VALUE    # Set header
reqsmith env set-auth TYPE CONFIG     # Set authentication

# Environment operations
reqsmith env validate [NAME]          # Validate environment
reqsmith env test [NAME]              # Test environment
reqsmith env export NAME              # Export environment
reqsmith env delete NAME              # Delete environment

Environment Options​

# Display options
--details                       # Show detailed information
--show-variables               # Include variables in output
--resolve-variables            # Resolve variable values
--format FORMAT                # Output format (yaml, json, table)

# Creation options
--template TEMPLATE            # Use environment template
--from-current                 # Copy from current environment
--base-url URL                 # Set base URL
--description TEXT             # Set description

# Security options
--encrypt                      # Encrypt sensitive data
--sanitize                     # Remove sensitive information
--require-confirmation         # Require confirmation for changes

# Import/Export options
--output FILE                  # Output file
--include-templates            # Include template references
--include-docs                 # Include documentation
--overwrite                    # Overwrite existing environment

# Validation options
--schema FILE                  # Validate against schema
--check-connectivity           # Test network connectivity
--fail-on-error               # Exit on validation error

Best Practices​

  1. Use descriptive names: Give environments clear, meaningful names
  2. Document thoroughly: Add descriptions explaining environment purpose
  3. Secure credentials: Use environment variables for sensitive data
  4. Version control: Keep environment configs in version control
  5. Validate regularly: Test environment configurations frequently
  6. Isolate environments: Maintain strict separation between environments
  7. Use templates: Create reusable environment templates
  8. Monitor usage: Track environment usage and performance
  9. Regular cleanup: Remove unused environments and variables
  10. Team coordination: Coordinate environment changes with team

Examples​

Complete Environment Configuration​

# environments/production.yaml
name: production
description: Production API environment for MyApp
version: 2.1

# Base configuration
base_url: https://api.myapp.com
timeout: 30000
retry_attempts: 3

# Variables
variables:
  api_version: v2
  user_agent: MyApp/2.1
  max_retries: 3
  cache_ttl: 3600

# Default headers
headers:
  User-Agent: "{{user_agent}}"
  Accept: application/json
  X-API-Version: "{{api_version}}"
  X-Environment: production

# Authentication
authentication:
  type: bearer
  token: "${PROD_API_TOKEN}"
  refresh_url: "{{base_url}}/auth/refresh"

# Network settings
network:
  timeout: "{{timeout}}"
  connect_timeout: 5000
  retry_attempts: "{{max_retries}}"
  retry_delay: 1000
  verify_ssl: true
  follow_redirects: true

# Caching configuration
cache:
  enabled: true
  ttl: "{{cache_ttl}}"
  max_size: 100MB
  strategy: cache-first

# Security settings
security:
  encrypt_credentials: true
  require_confirmation: true
  audit_requests: true

# Hooks
hooks:
  pre_request:
    - validate_token
    - log_request
  post_request:
    - update_metrics
    - check_rate_limits

Environment Workflow Example​

# Development workflow
reqsmith env create development \
  --template api-template \
  --base-url https://dev-api.myapp.com \
  --var debug=true

# Switch to development
reqsmith env switch development

# Test API endpoints
reqsmith get /users --env development

# Clone for staging
reqsmith env clone development staging \
  --set base_url=https://staging-api.myapp.com \
  --set debug=false

# Promote to production
reqsmith env promote staging production \
  --set base_url=https://api.myapp.com \
  --require-approval

Next Steps​