t2i

name: t2i version: 1.2.1 description: 'Use the t2i CLI to generate AI images from text prompts via Microsoft Foundry providers (FLUX.2, MAI-Image-2). Activate when the user asks to generate images, automate image creation in scripts, or set up image generation for CI/CD.' author: Bruno Capuano bruno@elbruno.com license: MIT tags: - text-to-image - image-generation - foundry - ai - cli - dotnet-tool - dotnet inputs: - prompt: string, required, text description of the image to generate - provider: string, optional, image generation provider (foundry-flux2 or foundry-mai2), default foundry-flux2 - output: string, optional, output file path for the generated image - width: integer, optional, image width in pixels, default 512 - height: integer, optional, image height in pixels, default 512 - steps: integer, optional, number of inference steps, default 20 outputs: - image: PNG file saved to specified output path or auto-generated filename - status: generation success/failure with error details on failure requirements: - dotnet-tool: ElBruno.Text2Image.Cli >=1.2.0 - runtime: '.NET 8.0 or .NET 10.0' entrypoint: t2i

t2i — Text-to-Image CLI Skill

This skill teaches AI agents (GitHub Copilot, Claude Code, and MCP-aware assistants) how to use the t2i command-line tool for image generation. Learn the commands, workflows, and best practices for automating text-to-image tasks in scripts and terminal environments.

When to Use This Skill

Activate this skill when:

• User asks to generate an image from a text prompt
• User mentions text-to-image, image generation, or AI images
• User wants to automate image generation in a script or pipeline
• User needs batch image generation across multiple prompts
• User is setting up image generation for CI/CD or deployment workflows
• User requests help with t2i command syntax or configuration

Quick Reference

Core Commands

Generate Command Flags

Config Command Actions

t2i config              # Launch interactive wizard
t2i config show         # Display all configuration
t2i config set <key> <value>  # Set config value (e.g., foundry-flux2.endpoint)
t2i config set-all <field> <value>  # Set a shared field for ALL cloud providers (e.g., set-all apiKey <key>)
t2i config remove <provider>  # Remove provider config and secrets
t2i config path         # Show config file location

Secrets Command Actions

t2i secrets set <provider>       # Interactively set secrets
t2i secrets list                 # Show all secrets (redacted)
t2i secrets remove <provider>    # Remove all secrets for provider
t2i secrets remove <provider> --field <name>  # Remove specific field
t2i secrets test <provider>      # Test provider connection

Init Command Targets

t2i init                 # Create or update skill files for GitHub and Claude (default: update existing)
t2i init --target github # Create/update .github/skills/t2i/SKILL.md only
t2i init --target claude # Create/update .claude/skills/t2i/SKILL.md only
t2i init --keep-existing # Skip files that already exist (do not update)

Providers

Two cloud providers available in the Lite edition:

Default: foundry-flux2 if user doesn't specify --provider.

Provider Decision Tree

Choose foundry-flux2 if:

• You need the highest quality images
• You're working on production assets
• Fine-grained control over generation parameters is important
• You can wait 10-30 seconds for results

Choose foundry-mai2 if:

• You need fast iteration (< 10 seconds)
• You're prototyping or experimenting
• Your prompts are conversational or complex
• You prefer synchronous API responses

Required Configuration

Both providers require:

• endpoint — Microsoft Foundry API endpoint (set via t2i config set <provider>.endpoint <url>)
• apiKey — API key for authentication (set securely via t2i secrets set <provider>)

Common Workflows

1. First-Time Setup

# Step 1: Interactive config
t2i config

# Step 2: Enter API credentials when prompted
# (CLI stores securely via DPAPI on Windows, encrypted on macOS/Linux)

# Step 3: Verify connection
t2i doctor

# Step 4: Generate your first image
t2i "a robot painting a landscape"

Agent tip: If user skips t2i config, they'll get a "not configured" error. Always suggest running it first.

2. Generate One Image

# Basic: uses default provider and outputs to current directory
t2i "a cyberpunk city at night, neon lights"

# With custom filename
t2i "a robot waving" --output my-robot.png

# Specific provider and dimensions
t2i "minimalist line art of a cat" \
  --provider foundry-mai2 \
  --width 1024 \
  --height 1024 \
  --output cat.png

# High-quality image with more inference steps
t2i "photorealistic mountain landscape" \
  --steps 50 \
  --width 1920 \
  --height 1080 \
  --output landscape.png

Output: Images are saved to the specified path or auto-generated filename <prompt-slug>-<timestamp>.png

3. Batch Generate via Shell Loop

Bash:

#!/bin/bash
prompts=(
  "a robot painting a landscape"
  "a cyberpunk city at night"
  "a watercolor painting of a castle"
)

for i in "${!prompts[@]}"; do
  prompt="${prompts[$i]}"
  echo "Generating $((i+1))/${#prompts[@]}: $prompt"
  t2i "$prompt" --output "image-$(printf '%02d' $((i+1))).png"
  sleep 2  # rate limiting
done

PowerShell:

$prompts = @(
    "a robot painting a landscape",
    "a cyberpunk city at night",
    "a watercolor painting of a castle"
)

for ($i = 0; $i -lt $prompts.Count; $i++) {
    $prompt = $prompts[$i]
    Write-Host "Generating $($i+1)/$($prompts.Count): $prompt"
    $index = ($i + 1).ToString("D2")
    & t2i $prompt --output "image-$index.png"
    Start-Sleep -Seconds 2  # rate limiting
}

4. CI/CD Integration (GitHub Actions)

name: Generate Marketing Assets

on:
  workflow_dispatch:
  schedule:
    - cron: '0 0 * * 1'  # Weekly on Monday

jobs:
  generate-images:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Install t2i
        run: dotnet tool install -g ElBruno.Text2Image.Cli

      - name: Generate hero image
        env:
          T2I_FOUNDRY_FLUX2_ENDPOINT: ${{ secrets.T2I_ENDPOINT }}
          T2I_FOUNDRY_FLUX2_API_KEY: ${{ secrets.T2I_API_KEY }}
        run: |
          t2i "futuristic tech product hero image" \
            --output assets/hero.png \
            --width 1920 \
            --height 1080

      - name: Upload artifacts
        uses: actions/upload-artifact@v4
        with:
          name: generated-images
          path: assets/*.png

5. Troubleshooting Workflow

# Step 1: Check system health and configuration
t2i doctor

# Step 2: List all providers and their status
t2i providers

# Step 3: Verify secrets are configured
t2i secrets list

# Step 4: Test specific provider connectivity
t2i secrets test foundry-flux2

# Step 5: View current configuration
t2i config show

# Step 6: Check config file location
t2i config path

6. Updating the Tool

# Step 1: Check if an update is available
t2i update

# Step 2: If update is available, confirm the prompt (or use --auto)
# Step 3: Review the new version after update
t2i version

Automatic update (no confirmation prompt):

t2i update --auto

Important Rules for Agents

1. Always Verify Configuration First

Before suggesting any image generation command, check if the user has run t2i config. If they haven't or see configuration errors, suggest:

t2i config  # Interactive setup
# OR
t2i doctor  # Check current status

2. Never Expose API Keys

DO NOT:

• Include API keys, tokens, or secrets in code examples
• Display secrets in commit messages or logs
• Use --api-key flag in scripts (use secrets store instead)

ALWAYS:

• Direct users to t2i secrets set <provider> for credential management
• Use environment variables in CI/CD: T2I_<PROVIDER>_<FIELD>
• Store locally via DPAPI (Windows) or encrypted files (macOS/Linux)

3. Use Predictable Filenames in Scripts

When scripting batch jobs, always specify --output:

# GOOD: predictable, parseable filenames
t2i "prompt" --output "image-01.png"

# BAD: random filenames are hard to track
t2i "prompt"  # generates "prompt-slug-20240315-143022.png"

4. Default to foundry-flux2

If the user doesn't specify a provider:

• Use foundry-flux2 for best quality
• Only suggest foundry-mai2 if speed is critical or user prefers it

5. Run t2i doctor for Diagnostics

If the user reports generation failures or API errors:

t2i doctor  # One command checks everything:
            # - System info
            # - Provider availability
            # - Configuration status
            # - Secret store health

6. Suggest t2i init for New Repos & Updates

When onboarding a new project or updating skill files:

t2i init  # Creates or updates skill files for AI agents
          # - .github/skills/t2i/SKILL.md
          # - .claude/skills/t2i/SKILL.md
          # By default, existing files are updated with latest content
          # Use --keep-existing to preserve existing files

7. Respect Rate Limits

When generating multiple images:

# Add delays between requests
for prompt in prompts; do
  t2i "$prompt" --output "image-$i.png"
  sleep 2  # 2 second delay
done

Using t2i with AI Coding Agents

GitHub Copilot CLI Integration

Once you run t2i init, GitHub Copilot CLI can discover and use this skill automatically:

Example prompts:

"Generate a logo image and save it as logo.png"
→ Copilot will run: t2i "company logo, modern design" --output logo.png

"Create test images for my gallery using different styles"
→ Copilot will batch generate with various prompts

"Show me what t2i commands are available"
→ Copilot will reference this skill file

Claude Code Integration

After t2i init --target claude, Claude can assist with:

• Script automation for batch generation
• CI/CD pipeline setup
• Troubleshooting configuration issues
• Workflow optimization

Example workflow:

User: "Help me set up image generation in CI"
Claude: "Let's configure GitHub Actions for t2i:
1. Run 't2i config' locally to test
2. Add secrets to GitHub repo settings
3. Create workflow file with env vars
4. Test with workflow_dispatch"

Secrets & Security

Storage Priority

t2i checks for secrets in this order:

1. Environment variables — T2I_<PROVIDER>_<FIELD> (best for CI/CD)

   # Example for foundry-flux2
   export T2I_FOUNDRY_FLUX2_ENDPOINT="https://..."
   export T2I_FOUNDRY_FLUX2_API_KEY="your-key-here"
   

2. Platform-specific secure storage:

   • Windows: DPAPI encrypted file at %LOCALAPPDATA%\t2i\secrets.dpapi (per-user encryption)
   • macOS/Linux: File at ~/.config/t2i/secrets.json with 0600 permissions

3. Config overrides — --endpoint and --api-key flags (NOT RECOMMENDED for scripts)

Local Development Setup

Interactive (recommended):

t2i secrets set foundry-flux2
# Prompts for: endpoint, apiKey
# Stores securely via DPAPI/encrypted file

Manual (environment variables):

# Windows PowerShell
$env:T2I_FOUNDRY_FLUX2_ENDPOINT = "https://..."
$env:T2I_FOUNDRY_FLUX2_API_KEY = "..."

# Linux/macOS
export T2I_FOUNDRY_FLUX2_ENDPOINT="https://..."
export T2I_FOUNDRY_FLUX2_API_KEY="..."

CI/CD Setup

GitHub Actions:

name: Generate Images

on: [push]

jobs:
  generate:
    runs-on: ubuntu-latest
    steps:
      - name: Install t2i
        run: dotnet tool install -g ElBruno.Text2Image.Cli

      - name: Generate
        env:
          T2I_FOUNDRY_FLUX2_ENDPOINT: ${{ secrets.T2I_ENDPOINT }}
          T2I_FOUNDRY_FLUX2_API_KEY: ${{ secrets.T2I_API_KEY }}
        run: t2i "test image" --output output.png

Azure Pipelines:

steps:
- task: DotNetCoreCLI@2
  inputs:
    command: 'custom'
    custom: 'tool'
    arguments: 'install -g ElBruno.Text2Image.Cli'

- script: t2i "azure logo" --output logo.png
  env:
    T2I_FOUNDRY_FLUX2_ENDPOINT: $(T2I_ENDPOINT)
    T2I_FOUNDRY_FLUX2_API_KEY: $(T2I_API_KEY)

Security Best Practices

DO:

• ✓ Use t2i secrets set for local development
• ✓ Store secrets in CI/CD secret managers (GitHub Secrets, Azure Key Vault)
• ✓ Use environment variables in automated workflows
• ✓ Add secret paths to .gitignore:

  # Windows
  %LOCALAPPDATA%/t2i/secrets.dpapi
  
  # macOS/Linux
  ~/.config/t2i/secrets.json
  

DON'T:

• ✗ Hardcode API keys in scripts or config files
• ✗ Commit secrets to version control
• ✗ Use --api-key flag in shared scripts
• ✗ Share secret store files between users

Rotating Credentials

# Update existing secrets
t2i secrets set foundry-flux2

# Verify new secrets work
t2i secrets test foundry-flux2

# Remove old secrets
t2i secrets remove foundry-flux2 --field apiKey

Troubleshooting

Common Errors and Solutions

Error: "No default provider configured"

Cause: User hasn't run initial configuration.

Solution:

t2i config  # Interactive setup
# OR
t2i config set foundry-flux2.endpoint "https://..."
t2i secrets set foundry-flux2

Error: "Provider 'X' not found"

Cause: Invalid provider name.

Solution:

t2i providers  # List all available providers
# Valid providers: foundry-flux2, foundry-mai2, foundry-mai25, foundry-mai25-flash

Error: "Missing secret 'apiKey' for provider"

Cause: API credentials not configured.

Solution:

# Interactive
t2i secrets set foundry-flux2

# OR via environment variable
export T2I_FOUNDRY_FLUX2_API_KEY="your-key"

Error: "Generation failed: 401 Unauthorized"

Cause: Invalid or expired API key.

Solution:

# Test connectivity
t2i secrets test foundry-flux2

# Rotate credentials
t2i secrets set foundry-flux2

Error: "Generation failed: 429 Too Many Requests"

Cause: Rate limit exceeded.

Solution:

# Add delays in batch scripts
sleep 2  # Bash
Start-Sleep -Seconds 2  # PowerShell

Error: "Could not write to output path"

Cause: Permission issues or invalid path.

Solution:

# Check permissions
ls -la output-dir/  # Linux/macOS
Get-Acl output-dir\  # Windows

# Use absolute path
t2i "prompt" --output "/full/path/to/image.png"

Diagnostic Commands

Run these in order when troubleshooting:

# 1. Check overall health
t2i doctor

# 2. View current configuration
t2i config show

# 3. List configured providers
t2i providers

# 4. Check secrets
t2i secrets list

# 5. Test specific provider
t2i secrets test foundry-flux2

# 6. Find config file
t2i config path

Log Files and Debugging

Check config location:

t2i config path
# Windows: %APPDATA%\t2i\config.json
# macOS: ~/Library/Application Support/t2i/config.json
# Linux: ~/.config/t2i/config.json

Manually inspect config:

# Windows PowerShell
cat $env:APPDATA\t2i\config.json

# Linux/macOS
cat ~/.config/t2i/config.json

Reset configuration:

# Remove provider config
t2i config remove foundry-flux2

# Remove all secrets
t2i secrets remove foundry-flux2

# Start fresh
t2i config

Getting Help

If you're still stuck:

1. Run full diagnostics:

   t2i doctor > diagnostics.txt
   t2i config show >> diagnostics.txt
   t2i providers >> diagnostics.txt
   

2. Check documentation:

   • Full CLI docs: docs/cli-tool.md
   • GitHub repo: elbruno/ElBruno.Text2Image

3. Report issues:

   • GitHub Issues: Report a bug
   • Include: t2i version, t2i doctor output, error messages

Examples for AI Agents

Good Agent Behavior ✓

Example 1: User asks to generate an image

User: "Create a logo for my startup"
Agent: 
1. Checks: "Have you configured t2i? Run 't2i doctor' to verify."
2. User confirms setup is done
3. Agent runs: t2i "modern startup logo, minimalist design" --output logo.png
4. Verifies output exists: ls -la logo.png

Example 2: User reports error

User: "t2i command failed with 'missing secret' error"
Agent:
1. Runs: t2i secrets list
2. Identifies missing apiKey
3. Suggests: "Run 't2i secrets set foundry-flux2' to configure credentials"
4. After setup, tests: t2i secrets test foundry-flux2

Example 3: Batch generation

User: "Generate 5 test images"
Agent:
1. Creates script with --output for each image
2. Adds sleep delays between requests
3. Runs script and verifies all outputs exist
4. Reports: "Generated 5 images: image-01.png through image-05.png"

Bad Agent Behavior ✗

Don't do this:

# ✗ Exposing API keys
t2i "prompt" --api-key "sk-abc123..."

# ✗ No output specification in scripts
for i in {1..10}; do
  t2i "prompt"  # Random filenames!
done

# ✗ Skipping configuration check
t2i "prompt"  # Fails with "not configured"

# ✗ No rate limiting
for prompt in prompts; do
  t2i "$prompt"  # Too fast!
done

Do this instead:

# ✓ Use secrets store
t2i secrets set foundry-flux2

# ✓ Specify output paths
for i in {1..10}; do
  t2i "prompt" --output "image-$(printf '%02d' $i).png"
  sleep 2
done

# ✓ Check config first
t2i doctor && t2i "prompt"

# ✓ Add delays
for prompt in prompts; do
  t2i "$prompt" --output "img-$i.png"
  sleep 2
done

More Info

• Full documentation: docs/cli-tool.md
• GitHub repository: elbruno/ElBruno.Text2Image
• Package: NuGet: ElBruno.Text2Image.Cli
• Report issues: GitHub Issues