How TeamAI Manages Environment Variable Injection Across Developer Tools

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 file inside the team repository. The schema for this file is defined in 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 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, 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. 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 file. This block is delimited by specific markers defined in 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, 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 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 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 module removes these injected blocks when TeamAI is uninstalled.

Managing Environment Variables via CLI

TeamAI provides dedicated CLI commands in src/env-commands.ts for interacting with environment variables:

# 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, validated by EnvYamlSchema using Zod in src/resources/env.ts.

• Secure generation: The generateEnvFile() function creates 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.

• Bidirectional sync: scanLocalForPush() detects local changes for pushing, while 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. This utility carefully quotes every variable value before writing it to the generated 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 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 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 processes the remote env.yaml and regenerates 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 becomes the source of truth after a pull.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}