# How TeamAI Manages Environment Variable Injection Across Developer Tools

> TeamAI centralizes env variable injection via a shell script and guarded blocks for secure, cross-tool synchronization across developer tools.

- Repository: [Tencent/teamai-cli](https://github.com/tencent/teamai-cli)
- Tags: how-to-guide
- Published: 2026-09-11

---

**TeamAI manages environment variable injection through a centralized `env` resource that generates a sourceable shell script and injects guarded blocks into user shell profiles, ensuring secure, cross-tool synchronization.**

TeamAI synchronizes environment variables through a dedicated **`env`** resource type defined in the Tencent/teamai-cli repository. This system allows development teams to share configuration securely across different tools and shells by centralizing definitions in YAML and generating machine-local shell scripts that are automatically sourced into the user's environment.

## Centralized Environment Variable Configuration

Every team stores its shared variables in a single [`env/env.yaml`](https://github.com/Tencent/teamai-cli/blob/main/env/env.yaml) file inside the team repository. The schema for this file is defined in [`src/resources/env.ts`](https://github.com/Tencent/teamai-cli/blob/main/src/resources/env.ts) within the `EnvYamlSchema` object and parsed using **Zod** to ensure type safety and validation.

During the pull workflow, the `EnvHandler` reads this YAML configuration and writes it to a machine-local backup while generating an executable shell script. This generation occurs in the `generateEnvFile()` function, where each value is safely quoted using `shellQuoteValue()` to prevent shell injection attacks.

## Secure Shell Script Generation

The [`env.sh`](https://github.com/Tencent/teamai-cli/blob/main/env.sh) script produced by TeamAI contains safe `export` statements that can be sourced by any POSIX-compatible shell. According to the implementation in [`src/resources/env.ts`](https://github.com/Tencent/teamai-cli/blob/main/src/resources/env.ts), the generation process carefully handles value escaping between lines 42 and 44, ensuring that special characters do not break shell syntax or create security vulnerabilities.

### Injection Prevention with shellQuoteValue

The `shellQuoteValue()` utility function wraps variable values in appropriate quoting logic before writing to [`env.sh`](https://github.com/Tencent/teamai-cli/blob/main/env.sh). This defensive programming pattern prevents command injection when variables contain user-generated content or special shell characters like quotes, dollar signs, or backticks.

## Profile Injection Mechanics

TeamAI modifies the user's shell profile (`.bashrc` or `.zshrc`) by inserting a managed block that sources the generated [`env.sh`](https://github.com/Tencent/teamai-cli/blob/main/env.sh) file. This block is delimited by specific markers defined in [`src/types.ts`](https://github.com/Tencent/teamai-cli/blob/main/src/types.ts) at lines 737-738: `# [teamai:env:start]` and `# [teamai:env:end]`.

The `generateShellBlock()` function constructs this reference block, while `injectShellProfile()` handles the actual insertion or update operation in the user's profile file. If the markers already exist, TeamAI updates the content between them; otherwise, it appends the block to the end of the profile.

## Sync Workflow: Pull and Push Operations

The environment variable injection system operates bidirectionally through the standard TeamAI sync workflow.

### Detecting Changes with scanLocalForPush

During a **push** operation, `EnvHandler.scanLocalForPush()` detects changes to [`env.yaml`](https://github.com/Tencent/teamai-cli/blob/main/env.yaml), including untracked or modified files. When the repository operates in *self-mode* (single-repo workflow), this function copies the active environment configuration into the worktree, ensuring the central repository stays synchronized with local modifications.

### Pull-Time Injection via pull.ts

When a **pull** occurs, [`pull.ts`](https://github.com/Tencent/teamai-cli/blob/main/pull.ts) recognizes resources of type `env` and orchestrates the injection process. The workflow counts variables using `countEnvVars()` and invokes `pullItem()` to write the updated [`env.sh`](https://github.com/Tencent/teamai-cli/blob/main/env.sh) file to the data home directory. Immediately after, it triggers the profile injection logic to update shell configuration files with the new source reference.

## Cross-Tool Consumption

All downstream tools and CLI applications consume these variables by sourcing `~/.teamai/env.sh` (or the equivalent path returned by `getDataHome()`). The injected profile block ensures this happens automatically for every new shell session, making variables available through `process.env` in Node.js applications, Python scripts, or any other executable that inherits the shell environment. For cleanup, the [`src/uninstall.ts`](https://github.com/Tencent/teamai-cli/blob/main/src/uninstall.ts) module removes these injected blocks when TeamAI is uninstalled.

## Managing Environment Variables via CLI

TeamAI provides dedicated CLI commands in [`src/env-commands.ts`](https://github.com/Tencent/teamai-cli/blob/main/src/env-commands.ts) for interacting with environment variables:

```bash

# List environment variables (masked by default)

teamai env list

# Show clear-text values (use with caution)

teamai env list --reveal

# Add or update a variable locally (changes are staged until push)

teamai env add API_KEY secret123 --description "Key for external API"

# Remove a variable locally

teamai env remove API_KEY

# Sync local changes to the team repository

teamai push

# Fetch latest environment configuration from team repository

teamai pull

```

## Summary

- **Centralized definitions**: Teams store variables in [`env/env.yaml`](https://github.com/Tencent/teamai-cli/blob/main/env/env.yaml), validated by `EnvYamlSchema` using Zod in [`src/resources/env.ts`](https://github.com/Tencent/teamai-cli/blob/main/src/resources/env.ts).
- **Secure generation**: The `generateEnvFile()` function creates [`env.sh`](https://github.com/Tencent/teamai-cli/blob/main/env.sh) with values escaped via `shellQuoteValue()` to prevent injection.
- **Profile injection**: `injectShellProfile()` inserts guarded blocks between `# [teamai:env:start]` and `# [teamai:env:end]` markers defined in [`src/types.ts`](https://github.com/Tencent/teamai-cli/blob/main/src/types.ts).

- **Bidirectional sync**: `scanLocalForPush()` detects local changes for pushing, while [`pull.ts`](https://github.com/Tencent/teamai-cli/blob/main/pull.ts) handles re-generation and re-injection during pulls.
- **Universal access**: All tools source the generated script from the data home directory, enabling consistent `environment variable injection` across the development stack.

## Frequently Asked Questions

### How does TeamAI prevent shell injection when exporting variables?

TeamAI prevents shell injection through the `shellQuoteValue()` function implemented in [`src/resources/env.ts`](https://github.com/Tencent/teamai-cli/blob/main/src/resources/env.ts). This utility carefully quotes every variable value before writing it to the generated [`env.sh`](https://github.com/Tencent/teamai-cli/blob/main/env.sh) script, ensuring that malicious characters cannot escape the export statement or execute arbitrary commands when the file is sourced.

### What happens to my shell profile when I uninstall TeamAI?

The uninstallation process defined in [`src/uninstall.ts`](https://github.com/Tencent/teamai-cli/blob/main/src/uninstall.ts) automatically locates and removes the injected shell blocks delimited by `# [teamai:env:start]` and `# [teamai:env:end]` markers. This cleanup restores your `.bashrc` or `.zshrc` to its state prior to TeamAI installation, removing all references to the generated [`env.sh`](https://github.com/Tencent/teamai-cli/blob/main/env.sh) file.

### Can I use TeamAI environment variables with languages other than shell scripts?

Yes. Any process that inherits the shell environment can access variables managed by TeamAI. Once the profile block injects `source ~/.teamai/env.sh` into your shell initialization, variables become available to Node.js via `process.env`, Python via `os.environ`, and any other runtime that accesses the standard environment variable namespace.

### How does TeamAI handle conflicts between local and remote environment variables?

During a pull operation, [`pull.ts`](https://github.com/Tencent/teamai-cli/blob/main/pull.ts) processes the remote [`env.yaml`](https://github.com/Tencent/teamai-cli/blob/main/env.yaml) and regenerates [`env.sh`](https://github.com/Tencent/teamai-cli/blob/main/env.sh) completely, overwriting the local backup. Local modifications are detected by `scanLocalForPush()` before a push occurs, allowing you to sync local changes to the team repository. The system does not perform merge conflict resolution for individual variables; the remote state from [`env.yaml`](https://github.com/Tencent/teamai-cli/blob/main/env.yaml) becomes the source of truth after a pull.