# How to Manage Secrets and Environment Variables for Different Agents-CLI Deployment Targets

> Master secrets and environment variables for agents-cli deployments. Learn a layered approach using .env files, Terraform, CI/CD, and runtime helpers for secure and efficient management across development and production.

- Repository: [Google/agents-cli](https://github.com/google/agents-cli)
- Tags: how-to-guide
- Published: 2026-07-01

---

**Use a layered approach where local development relies on `.env` files, production deployments inject secrets via Terraform and CI/CD pipelines, and runtime code reads standardized environment variables through language-specific helpers.**

The `google/agents-cli` framework supports multiple deployment targets including Cloud Run, GKE, and Agent Runtime. Each environment requires distinct configuration values and secrets, from API keys to project identifiers. The scaffold provides a consistent pattern for handling these across local development and production deployments.

## Local Development Configuration

During local development, agents-cli projects use environment files to simulate production configuration without hardcoding sensitive values.

### Go Projects and godotenv

Go-based scaffolds automatically load local environment variables from a `.env` file. In [`src/google/agents/cli/scaffold/base_templates/go/main.go`](https://github.com/google/agents-cli/blob/main/src/google/agents/cli/scaffold/base_templates/go/main.go), the initialization code uses `godotenv.Load` to import local settings:

```go
import (
    "os"
    "github.com/joho/godotenv"
)

func init() {
    // Load .env only when it exists; production injects env vars via the platform
    _ = godotenv.Load(".env")
}

// Example usage
projectID := os.Getenv("GOOGLE_CLOUD_PROJECT")
appURL := os.Getenv("APP_URL")

```

This pattern ensures that local secrets override defaults while allowing the application to fail gracefully when the file is absent in production.

### Python Projects and Environment Variables

Python scaffolds read configuration directly through `os.getenv`. While the base templates do not mandate a specific `.env` loader, you can use `python-dotenv` or `uv run` commands to load local files. The ADK helper in `src/google/agents/cli/scaffold/base_templates/python/{{cookiecutter.agent_directory}}/app_utils/a2a.py` defines standard variables:

```python
import os

# Common variables used by the ADK helper

APP_URL = os.getenv("APP_URL", "http://0.0.0.0:8000")
PROJECT_ID = os.getenv("GOOGLE_CLOUD_PROJECT")
AGENT_ENGINE_ID = os.getenv("GOOGLE_CLOUD_AGENT_ENGINE_ID")
AGENT_LOCATION = os.getenv("GOOGLE_CLOUD_AGENT_ENGINE_LOCATION", "us-east1")

```

## Production Deployment Patterns

Production deployments leverage infrastructure-as-code and CI/CD systems to inject secrets securely without exposing them in source control.

### Terraform Variable Injection

The scaffold generates a `deployment/` directory containing Terraform scripts that export variables as Cloud Run or GKE environment variables. As shown in [`src/google/agents/cli/scaffold/base_templates/python/README.md`](https://github.com/google/agents-cli/blob/main/src/google/agents/cli/scaffold/base_templates/python/README.md), you define variables in Terraform configuration:

```hcl
variable "app_url" {
  description = "Base URL for the agent service"
}

variable "agent_api_key" {
  description = "API key for the external service"
  type        = string
  sensitive   = true
}

resource "google_cloud_run_service" "agent" {
  # …

  env {
    name  = "APP_URL"
    value = var.app_url
  }
  env {
    name  = "AGENT_API_KEY"
    value = var.agent_api_key
  }
}

```

When Terraform applies the plan, these values populate the runtime environment, accessible via standard library calls.

### CI/CD Secret Management

For the `agents-cli publish` command, secrets such as `AGENT_CARD_URL`, `ID`, and `GEMINI_ENTERPRISE_APP_ID` are read from the environment at execution time. In [`src/google/agents/cli/publish/cmd_publish.py`](https://github.com/google/agents-cli/blob/main/src/google/agents/cli/publish/cmd_publish.py), the implementation expects these values to be set by your CI pipeline.

Configure GitHub Actions or Cloud Build to inject secrets from Google Secret Manager or GitHub Secrets:

```yaml
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Set secret as env var
        env:
          AGENT_API_KEY: ${{ secrets.AGENT_API_KEY }}
        run: |
          export AGENT_API_KEY=$AGENT_API_KEY
          agents-cli deploy --deployment-target=cloud_run

```

## Runtime Configuration Retrieval

At runtime, agents retrieve configuration through language-agnostic helpers that abstract platform differences.

### Go Runtime Implementation

Go agents use `os.Getenv` to obtain values such as `GOOGLE_CLOUD_PROJECT` and `APP_URL`. The implementation in [`src/google/agents/cli/scaffold/base_templates/go/main.go`](https://github.com/google/agents-cli/blob/main/src/google/agents/cli/scaffold/base_templates/go/main.go) demonstrates this pattern for both required and optional configuration.

### Python Runtime Implementation

Python agents follow the same pattern. Target-specific implementations like `src/google/agents/cli/scaffold/deployment_targets/gke/python/{{cookiecutter.agent_directory}}/fast_api_app.py` read optional values such as `ALLOW_ORIGINS` to configure CORS settings specific to the deployment environment.

## Target-Specific Scaffold Generation

The `agents-cli create` command uses the `deployment_target` flag (e.g., `cloud_run`, `gke`, `agent_runtime`, `none`) to generate appropriate configuration files. In [`src/google/agents/cli/scaffold/utils/template.py`](https://github.com/google/agents-cli/blob/main/src/google/agents/cli/scaffold/utils/template.py), the template engine substitutes target-specific values and ensures each deployment target receives its own set of environment files and Terraform modules.

When switching targets, update the flag:

```bash
agents-cli create --deployment-target=gke

```

This generates the correct Terraform modules and environment variable wiring for GKE-specific deployment patterns.

## Summary

- **Local development**: Use `.env` files with `godotenv` (Go) or `python-dotenv` (Python) to simulate configuration without committing secrets.
- **Production deployment**: Inject secrets via Terraform variables and CI/CD environment variables, storing actual values in Google Secret Manager or GitHub Secrets.
- **Runtime access**: Retrieve configuration using `os.Getenv` (Go) or `os.getenv` (Python) through standardized helper modules.
- **Target switching**: Use the `--deployment-target` flag to generate scaffold-specific configurations for Cloud Run, GKE, or Agent Runtime.
- **Publish workflow**: Provide `AGENT_CARD_URL`, `ID`, and `GEMINI_ENTERPRISE_APP_ID` via environment variables when running `agents-cli publish`.

## Frequently Asked Questions

### How does agents-cli handle secrets differently for local development versus production?

Local development uses `.env` files loaded by `godotenv.Load(".env")` in Go or optional dotenv loaders in Python, allowing developers to override settings without affecting production. Production deployments rely on Terraform and CI/CD pipelines to inject secrets as runtime environment variables, ensuring sensitive values never exist in source code.

### What environment variables are required for the agents-cli publish command?

The `agents-cli publish` command expects `AGENT_CARD_URL`, `ID`, and `GEMINI_ENTERPRISE_APP_ID` to be set in the environment. According to [`src/google/agents/cli/publish/cmd_publish.py`](https://github.com/google/agents-cli/blob/main/src/google/agents/cli/publish/cmd_publish.py), these values are read at execution time from the process environment, allowing integration with secret managers in CI/CD pipelines.

### Can I use the same Terraform configuration for both Cloud Run and GKE deployments?

No. The scaffold generates target-specific Terraform modules based on the `deployment_target` value. The template engine in [`src/google/agents/cli/scaffold/utils/template.py`](https://github.com/google/agents-cli/blob/main/src/google/agents/cli/scaffold/utils/template.py) ensures each target receives specialized configuration files. You should maintain separate variable definitions for each deployment target to handle platform-specific requirements like service account mappings or networking configurations.

### How do I switch between deployment targets without recreating my agent?

Use the `--deployment-target` flag when running `agents-cli create` to generate the appropriate scaffold files for your desired platform. While this generates new target-specific files, your core agent logic remains portable. Ensure your code reads configuration through standard environment variable accessors (`os.getenv` or `os.Getenv`) so it adapts automatically to the new runtime environment injected by the target's Terraform configuration.