Advanced CLI Configuration

Customize CLI Behavior for Your Team

The Architech CLI can be configured to match your team's workflow, genome sources, and organizational standards.

Configuration File

Location Priority

The CLI searches for configuration in this order:

Project-level: ./architech.config.json (highest priority)
User-level: ~/.architech/config.json
Global defaults: Built-in defaults

Creating Configuration

# Project-specific config
architech config init
 
# User-wide config
architech config init --global

Complete Configuration Schema

{
  "cache": {
    "enabled": true,
    "ttl": 86400,
    "maxSize": 104857600
  },
  "genomeSources": [
    "local:../my-genomes",
    "npm:@mycompany/genomes",
    "npm:@architech/marketplace"
  ],
  "genomeAliases": {
    "company-stack": "./genomes/enterprise.genome.ts",
    "backend": "npm:@company/backend-genome",
    "frontend": "npm:@company/frontend-genome",
    "mobile": "local:../shared/mobile.genome.ts"
  },
  "marketplaceSources": [
    "npm:@architech/marketplace",
    "npm:@company/internal-marketplace"
  ],
  "defaults": {
    "skipInstall": false,
    "verbose": false,
    "dryRun": false
  }
}

Configuration Options

Cache Settings

Control blueprint and module caching:

{
  "cache": {
    "enabled": true,           // Enable caching system
    "ttl": 86400,              // Time-to-live in seconds (24 hours)
    "maxSize": 104857600,      // Max cache size in bytes (100MB)
    "location": "~/.architech/cache"  // Cache directory
  }
}

When to disable caching:

Active marketplace development
Debugging blueprint issues
CI/CD environments (use fresh builds)

Genome Sources

Add custom genome repositories:

{
  "genomeSources": [
    "local:../shared-genomes",              // Local filesystem
    "npm:@mycompany/genomes",               // NPM package
    "git:https://github.com/org/genomes",   // Git repository (future)
    "https://cdn.example.com/genomes"       // HTTP(S) endpoint (future)
  ]
}

Source types:

local: - Relative or absolute file paths
npm: - NPM package name
git: - Git repository URL (coming soon)
https: - Remote HTTP endpoint (coming soon)

Genome Aliases

Create shorthand names for frequently-used genomes:

{
  "genomeAliases": {
    "api": "./genomes/microservice-api.genome.ts",
    "web": "./genomes/nextjs-webapp.genome.ts",
    "mobile": "npm:@company/mobile-genome",
    "standard": "local:../shared/company-standard.genome.ts"
  }
}

Then use:

architech new my-api --genome api        # → Uses microservice-api.genome.ts
architech new my-app --genome web        # → Uses nextjs-webapp.genome.ts
architech new ios-app --genome mobile    # → Uses @company/mobile-genome

Marketplace Sources

Configure which marketplaces to use:

{
  "marketplaceSources": [
    "npm:@architech/marketplace",        // Official marketplace (default)
    "npm:@company/internal-marketplace", // Company marketplace
    "local:../custom-marketplace"        // Local marketplace (development)
  ]
}

Resolution order:

Company marketplace (if listed first)
Official marketplace
Local marketplace (development)

Default Command Options

Set default flags for commands:

{
  "defaults": {
    "skipInstall": false,      // Skip npm install after generation
    "verbose": false,          // Enable verbose logging
    "dryRun": false,           // Preview without executing
    "force": false             // Force overwrite existing files
  }
}

Real-World Examples

Enterprise Configuration

For companies with strict standards:

{
  "genomeSources": [
    "npm:@acme/enterprise-genomes"
  ],
  "genomeAliases": {
    "backend-api": "npm:@acme/enterprise-genomes/microservice",
    "frontend-spa": "npm:@acme/enterprise-genomes/react-spa",
    "mobile-app": "npm:@acme/enterprise-genomes/react-native",
    "internal-tool": "npm:@acme/enterprise-genomes/admin-portal"
  },
  "marketplaceSources": [
    "npm:@acme/internal-marketplace"  // Only use company marketplace
  ],
  "defaults": {
    "verbose": true,            // Always show detailed logs
    "skipInstall": false        // Always install dependencies
  },
  "cache": {
    "enabled": false            // Disable cache in corporate env
  }
}

Team members just run:

architech new my-service --genome backend-api
# Automatically uses company's enterprise microservice genome

Open Source Team Configuration

For distributed teams with shared standards:

{
  "genomeSources": [
    "git:https://github.com/your-org/team-genomes",
    "npm:@architech/marketplace"
  ],
  "genomeAliases": {
    "team-standard": "git:https://github.com/your-org/team-genomes/standard.genome.ts",
    "experimental": "git:https://github.com/your-org/team-genomes/experimental.genome.ts"
  },
  "cache": {
    "enabled": true,
    "ttl": 3600  // 1 hour for active development
  }
}

Freelancer/Agency Configuration

For agencies managing multiple client projects:

{
  "genomeSources": [
    "local:~/my-genomes",
    "npm:@architech/marketplace"
  ],
  "genomeAliases": {
    "client-saas": "local:~/my-genomes/saas-starter.genome.ts",
    "client-landing": "local:~/my-genomes/landing-page.genome.ts",
    "client-blog": "local:~/my-genomes/blog.genome.ts",
    "prototype": "hello-world"
  },
  "defaults": {
    "verbose": false,
    "dryRun": false
  }
}

Configuration Precedence

When multiple config files exist, they're merged with this precedence:

1. Command-line flags (highest)
   ↓
2. Project config (./architech.config.json)
   ↓
3. User config (~/.architech/config.json)
   ↓
4. Built-in defaults (lowest)

Example:

# User config has: verbose: false
# Project config has: verbose: true
# Command uses: --quiet
 
# Result: quiet mode (CLI flag wins)

Managing Configuration

View Current Configuration

# Show effective configuration (all sources merged)
architech config show
 
# Show specific value
architech config get genomeSources

Set Values

# Set genome alias (project-level)
architech config set genomeAliases.backend "./genomes/api.genome.ts"
 
# Set genome source (user-level)
architech config set genomeSources "npm:@company/genomes" --global
 
# Enable verbose mode by default (project)
architech config set defaults.verbose true

Add to Arrays

# Add genome source
architech config add genomeSources "npm:@newcompany/genomes"
 
# Remove genome source
architech config remove genomeSources "npm:@oldcompany/genomes"

Environment Variables

Override configuration with environment variables:

# Disable cache
ARCHITECH_CACHE_ENABLED=false architech new my-app
 
# Set custom marketplace
ARCHITECH_MARKETPLACE=@company/marketplace architech new my-app
 
# Enable verbose mode
ARCHITECH_VERBOSE=true architech new my-app

Precedence:

CLI flags > Environment variables > Config files > Defaults

Best Practices

1. Team Consistency

Commit architech.config.json to your repository so all team members use the same genomes and sources.

2. User Personalization

Use ~/.architech/config.json for personal preferences (verbose mode, cache settings) that don't affect project structure.

3. CI/CD Configuration

In CI/CD pipelines:

{
  "cache": { "enabled": false },
  "defaults": { "skipInstall": true }
}

4. Security

Never commit credentials or secrets in config files. Use environment variables for sensitive data.

Troubleshooting

Config not loading?

# Check which config is being used
architech config show --debug
 
# Verify JSON syntax
cat architech.config.json | jq .

Genome not found with alias?

# List all configured sources and aliases
architech config get genomeSources
architech config get genomeAliases
 
# Check resolution
architech list-genomes --verbose

Cache issues?

# Clear cache
rm -rf ~/.architech/cache
 
# Disable cache temporarily
architech new my-app --genome saas --no-cache

Next Steps

Custom Modifiers → - Build AST transformations
Creating Marketplace → - Build complete marketplace
CLI Reference → - All CLI commands

Configuration is power. Set it once, benefit everywhere.

Custom Modifiers Marketplace Adapter Interface