Understanding Configuration Files

Learn about the configuration files in .eac/ and how they're managed by EAC.

Prerequisites: Completed Quick Start

What You'll Learn

By the end of this tutorial, you'll understand:

What configuration files exist in .eac/
Which files are created by commands vs. exist as system defaults
How to customize configurations when needed
Which files to commit to git
How CLIE CLI configuration relates (if using CLIE)

Configuration Overview

EAC uses a layered configuration system:

Layer	File/Directory	Purpose	Created By
EAC Config	`.eac/`	EAC settings	`eac init`
CLIE Config (optional)	`.clie/clie.yml`	Extension management	`clie init`

EAC Configuration

.eac/ (EAC Configuration)

Created by: eac init
Purpose: Configures how EAC behaves
Scope: Project-level (applies to all EAC commands)
Example content: AI provider settings, module configuration

CLIE CLI Configuration (Optional)

.clie/clie.yml (Framework Configuration)

Created by: clie init
Purpose: Manages which extensions are available when running EAC via CLIE
Scope: Framework-level (applies to all extensions)
Example content: Extension registry, Docker images
Only needed if running EAC via the CLIE container host

See CLIE CLI Architecture for detailed architecture explanation.

EAC Configuration

The `.eac/` Directory

After running eac init, you'll have a .eac/ directory in your repository. This directory contains configuration files that control how the EAC extension works.

File Categories

EAC configuration files fall into three categories:

1. User-Specific Files (Created by Init)

These files are created when you run eac init and contain your team or personal settings:

File	Purpose	Commit?
`ai-provider.yml`	AI provider configuration (API keys, models)	Optional (team config)
`ai-provider.personal.yml`	Personal AI overrides	❌ Never (personal secrets)

Example: ai-provider.yml

ai:
  provider: claude-api
  model: claude-3-haiku-20240307
  endpoint: https://api.anthropic.com/v1
  api_key: ${ANTHROPIC_API_KEY}

git:
  token: ${GIT_TOKEN}

When to edit:

Change AI model
Switch AI providers
Update API endpoints

2. System Defaults (Automatic Fallback)

System default configurations live in contracts/eac-core/0.1.0/defaults/. You don't need to create them - EAC automatically uses them.

File	Purpose	Need to Copy?
`ai-config.yml`	AI type definitions (specs, commit-message)	❌ No (uses system default)
`ai-provider.yml`	Default AI provider settings	❌ No (uses system default)
`blueprints.yml`	Blueprint component kind definitions (go, typescript, dockerfile, etc.)	❌ No (uses system default)
`tool-config.yml`	Tool definitions and resource configuration	❌ No (uses system default)
`security-tools.yml`	Security tool configurations	❌ No (uses system default)
`logging.yml`	Logging configuration	❌ No (uses system default)
`environments.yml`	Test environment definitions	❌ No (uses system default)
`test-suites.yml`	Test suite definitions (unit, integration, acceptance, production-verification)	❌ No (uses system default)
`testing-tags.yml`	Test tag definitions	❌ No (uses system default)
`registries.yml`	Container registry definitions	❌ No (uses system default)

How it works:

EAC uses a layered fallback system (similar to Git config):

User override (.eac/ai-config.yml) - checked first
System default (contracts/eac-core/0.1.0/defaults/) - fallback if not found
Hardcoded default (in code) - last resort

Example: Using system defaults

# This command works automatically - no ai-config.yml needed!
eac create spec my-module

# EAC automatically:
# 1. Checks .eac/ai-config.yml (not found)
# 2. Falls back to built-in system default ✓
# 3. Uses that configuration

When to customize:

Most users never need to customize these files. The system defaults work for typical use cases.

Advanced Customization

If you need to customize these configurations (rare), you can create your own versions in .eac/. Your versions will take precedence over system defaults. See advanced documentation for details.

3. Generated Files (Created by Commands)

These files are created by EAC commands and stored in your repository:

File	Created By	Purpose	Commit?
`repository.yml`	`eac init`	Repository metadata and discovered modules	✅ Yes
`books.yml`	`eac init`	Architecture patterns found in code	✅ Yes

Note on test-suites.yml: This file has system defaults (see Section 2 above) providing standard test suites (unit, integration, acceptance, production-verification). You can optionally generate a customized version:

File	Created By	Purpose	Commit?
`test-suites.yml`	`eac init` (optional)	Custom test suite configurations	✅ Yes (if customized)

Example: repository.yml (generated)

repository:
  name: eac
  type: monorepo
  root: /var/task

modules:
  - name: core
    path: go/core
    type: lib
    language: go

  - name: commands
    path: go/cli/eac
    type: cli
    language: go

When created:

# Run init to create repository.yml and books.yml
eac init

# System defaults for test-suites.yml work automatically

Can you edit them?

Yes! You can edit generated files after creation. But running the command again with --force will overwrite your changes:

# Regenerate (overwrites your edits!)
eac init --force

Configuration Workflow

Minimal Setup (Recommended)

For most users, you only need to create user-specific files:

# 1. Initialize with AI provider
eac init --ai-provider claude-api

# 2. Set API key in environment
export ANTHROPIC_API_KEY=sk-ant-your-key-here

# 3. Run commands (uses system defaults automatically!)
eac init
eac create spec my-module

# Result: Clean .eac/ with only user-specific files

Files created:

.eac/
├── ai-provider.yml          (your provider config)
└── (all other files use built-in system defaults)

Advanced Customization (Optional)

Most Users Don't Need This

The minimal setup covers 99% of use cases. Only proceed if you have specific customization requirements.

If you need custom AI type definitions or other advanced configurations, you can copy the system defaults:

# Copy system default files to your repository for customization
eac init --copy-templates

This copies configuration files like ai-config.yml, blueprints.yml, etc. to .eac/. You can then:

Edit the copied files to customize them
Commit your customizations to version control
EAC will automatically use your versions instead of system defaults

Example file structure after copying:

.eac/
├── ai-provider.yml          (created by init)
├── ai-config.yml            (copied with --copy-templates)
├── blueprints.yml           (copied with --copy-templates)
└── (other copied files...)

For details on the file formats, see the Init Command Reference.

What to Commit to Git

Always Commit

✅ Generated files (documents your repository structure)

repository.yml
books.yml

✅ Team configuration (optional, team decides)

ai-provider.yml (if sharing team config)

✅ Custom overrides (if you customized them)

ai-config.yml (only if you created a custom version)
blueprints.yml (only if you created a custom version)
test-suites.yml (only if you generated/customized it)
testing-tags.yml (only if you created a custom version)
etc.

Never Commit

❌ Personal secrets and preferences

*.personal.yml (personal API keys)
*.local.yml (local overrides)

Auto-Gitignored

EAC automatically adds these patterns to .gitignore:

# EAC local configuration (never commit)
.clie/*.local.yml
.eac/*.personal.yml

Common Scenarios

Scenario 1: "I just want it to work"

Use the minimal setup - no customization needed:

eac init --ai-provider claude-api
export ANTHROPIC_API_KEY=your-key
eac init

Result: One config file (ai-provider.yml), everything else uses system defaults.

Scenario 2: "I want to change the AI model"

Edit your provider config:

# Edit ai-provider.yml
vim .eac/ai-provider.yml

# Change the model:
# model: claude-3-opus-20240229

# Commands now use new model
eac create spec my-module

Scenario 3: "I want to customize AI types"

Rare Use Case

Most users don't need custom AI types. The defaults support all standard workflows.

If you have specific requirements, copy the system defaults first:

# Copy system template files
eac init --copy-templates

# Edit the file
vim .eac/ai-config.yml

# Commit your customization
git add .eac/ai-config.yml
git commit -m "Custom AI configuration"

Your custom configuration will override system defaults.

Scenario 4: "I need to reset to defaults"

Delete your custom override to use system default again:

# Remove custom override
rm .eac/ai-config.yml

# Now uses system default again
eac create spec my-module

File Resolution Priority

When EAC loads configuration files, it checks locations in order:

Priority 1: Your repository (.eac/ai-config.yml)
         ↓ not found
Priority 2: Built-in system defaults
         ↓ not found
Priority 3: Hardcoded defaults (in code)

This means:

If you create a file locally, it takes precedence
If not, system defaults are used automatically
You only customize what you need

Upgrading

With System Defaults (Recommended)

If you're using system defaults (most users):

Automatic upgrade:

Install new version of EAC CLI
System defaults automatically updated
No configuration changes needed

With Custom Overrides

If you've created custom configuration files:

Manual review:

Install new version of EAC CLI
Review release notes for configuration changes
Update your custom files if needed

Summary

File Type	When Created	Customizable	Commit
User-Specific	By `init`	Yes	Optional
System Defaults	Built into EAC	Via override	If overridden
Generated	By commands	Yes (careful)	Yes

Key Takeaway: You only need to run eac init. Everything else works automatically!

Next Steps

Explore commands: EAC Commands Guide - Task-oriented command guides
Creating CLIE extensions: Creating Extensions - Build containerized CLIE extensions (optional)
Learn about specifications: BDD Fundamentals - Understand Gherkin and BDD
If customizing (advanced): See reference documentation for configuration file formats

Tutorials | How-to Guides | Explanation | Reference

You are here: Tutorials — learning-oriented guides that take you through steps to complete a project.

Understanding Configuration Files

What You'll Learn

Configuration Overview

EAC Configuration

CLIE CLI Configuration (Optional)

EAC Configuration

The .eac/ Directory

File Categories

1. User-Specific Files (Created by Init)

2. System Defaults (Automatic Fallback)

3. Generated Files (Created by Commands)

Configuration Workflow

Minimal Setup (Recommended)

Advanced Customization (Optional)

What to Commit to Git

Always Commit

Never Commit

Auto-Gitignored

Common Scenarios

Scenario 1: "I just want it to work"

Scenario 2: "I want to change the AI model"

Scenario 3: "I want to customize AI types"

Scenario 4: "I need to reset to defaults"

File Resolution Priority

Upgrading

With System Defaults (Recommended)

With Custom Overrides

Summary

Next Steps

The `.eac/` Directory