CLI Commands Reference

Complete reference for all The Architech CLI commands.

architech new

Create a new project from a genome.

Syntax

architech new [project-name] [options]

Options

Examples

# Shorthand genome name (recommended)
architech new my-app --genome hello-world
architech new my-saas --genome saas-starter
 
# Interactive picker
architech new my-app
 
# Show available genomes first
architech new --list
 
# Dry run (preview without creating)
architech new my-app --genome saas-starter --dry-run
 
# File path (custom genomes)
architech new ../marketplace/genomes/custom.genome.ts
 
# Verbose output
architech new my-app --genome ai-app --verbose

Genome Resolution System

The CLI uses a strategy chain to resolve genome names to actual files. This enables shorthand names, aliases, and custom sources.

Resolution Strategies (Executed in Order)

1. File Path Strategy

• Trigger: Input contains / or ends with .ts or .js
• Example: ./my-custom.genome.ts, ../shared/company-standard.genome.ts
• Use case: Direct paths to custom genome files

2. Alias Resolution

• Trigger: Genome name matches an alias in architech.config.json
• Example: my-stack → ./genomes/company-standard.genome.ts
• Use case: Team-specific shortcuts

3. Local Marketplace Strategy

• Trigger: Shorthand name matches official genome
• Searches: ../marketplace/genomes/official/*.genome.ts
• Example: hello-world → 01-hello-world.genome.ts
• Use case: Development and local testing

4. NPM Package Strategy

• Trigger: Marketplace installed via npm
• Searches: node_modules/@thearchitech.xyz/marketplace/genomes/
• Example: saas-starter → installed package genome
• Use case: Production usage

5. Custom Source Strategy

• Trigger: Sources defined in config
• Searches: Configured genome sources (git repos, private registries)
• Example: npm:@company/genomes/enterprise-stack
• Use case: Enterprise genome libraries

Available Genome Names

architech list-genomes

List all available project genome templates.

Syntax

architech list-genomes [options]

Options

Examples

# List all genomes
architech list-genomes
 
# Filter by complexity
architech list-genomes --complexity simple
 
# Search by keyword
architech list-genomes --search payment
architech list-genomes --search ai
 
# Show detailed info
architech list-genomes --verbose

architech config

Manage Architech configuration.

Subcommands

architech config init

Create a default configuration file.

# Project-level config
architech config init
 
# Global user config
architech config init --global

Creates: architech.config.json or ~/.architechrc

Configuration File Schema

The architech.config.json file allows you to customize CLI behavior, add genome sources, and define aliases.

{
  "cache": {
    "enabled": true,
    "ttl": 86400
  },
  "genomeSources": [
    "local:../my-genomes",
    "npm:@mycompany/genomes",
    "git:https://github.com/myorg/genomes"
  ],
  "genomeAliases": {
    "my-stack": "./genomes/company-standard.genome.ts",
    "enterprise": "npm:@company/enterprise-stack",
    "team-standard": "local:../shared/team.genome.ts"
  }
}

Configuration Options

cache - Control blueprint caching

• enabled (boolean): Enable/disable caching (default: true)
• ttl (number): Time-to-live in seconds (default: 86400 = 24 hours)

genomeSources - Add custom genome sources

• local: prefix - Local file system paths
• npm: prefix - NPM packages
• git: prefix - Git repositories (future)

genomeAliases - Create shorthand names

• Map simple names to full paths
• Support local paths, NPM packages, URLs
• Enable team-wide standards

Examples

Company-Internal Genomes:

{
  "genomeSources": [
    "npm:@acme/genomes"
  ],
  "genomeAliases": {
    "backend": "npm:@acme/genomes/microservice",
    "frontend": "npm:@acme/genomes/spa",
    "mobile": "npm:@acme/genomes/react-native"
  }
}

Then use:

architech new api-service --genome backend

Team-Shared Genomes:

{
  "genomeSources": [
    "local:../team-genomes"
  ],
  "genomeAliases": {
    "standard": "../team-genomes/standard.genome.ts"
  }
}

Multiple Sources:

{
  "genomeSources": [
    "local:../custom-genomes",
    "npm:@architech/marketplace",
    "npm:@company/internal-genomes"
  ]
}

architech config show

Display current configuration.

architech config show

Shows the merged configuration from project and user levels.

architech config set

Set a configuration value.

architech config set <key> <value> [options]

Options:

• --global - Set in global user configuration

Examples:

# Set default marketplace
architech config set defaultMarketplace @mycompany/marketplace
 
# Set global config
architech config set defaultMarketplace @mycompany/marketplace --global

architech config add-source

Add a custom genome source.

architech config add-source [options]

Required Options:

• --name <name> - Source name
• --type <type> - Source type (local, git, npm, url)
• --path <path> - Source path or URL

Optional:

• --priority <number> - Priority (lower = higher priority, default: 10)
• --global - Add to global configuration

Examples:

# Add company genome source
architech config add-source \
  --name company-genomes \
  --type local \
  --path ../company-genomes \
  --priority 1
 
# Add from git repository (future)
architech config add-source \
  --name community \
  --type git \
  --path https://github.com/architech-community/genomes \
  --priority 5

architech add

Add features to an existing project.

Status: ⚠️ V2 Feature - Not Yet Implemented

Will be available in V2 to add modules incrementally to existing projects.

architech scale

Scale a project to monorepo structure.

Status: ⚠️ V2 Feature - Not Yet Implemented

Will be available in V2 for advanced project scaling.

architech marketplace

Explore and manage the marketplace.

Syntax

architech marketplace [subcommand]

See architech marketplace --help for available subcommands.

architech analyze

Analyze existing repository and detect architecture.

Syntax

architech analyze [options] <repo-url>

Examples:

# Analyze GitHub repository
architech analyze https://github.com/user/repo
 
# Analyze local project
architech analyze ./my-project --output genome.ts
 
# Generate genome file from analysis
architech analyze https://github.com/user/repo --output detected.genome.ts

Global Options

Available for all commands:

Configuration File

architech.config.json

{
  "version": "1.0.0",
  "defaultMarketplace": "@architech/marketplace",
  "genomeSources": [
    {
      "name": "local-development",
      "type": "local",
      "path": "../marketplace",
      "priority": 1,
      "enabled": true
    }
  ],
  "genomeAliases": {
    "my-custom": "company-custom-app"
  },
  "cache": {
    "enabled": true,
    "ttl": 3600
  }
}

Config Locations (Priority Order):

1. ./architech.config.json (Project-level)
2. ./.architechrc (Project-level)
3. ~/.architechrc (User-level)
4. ~/.config/architech/config.json (User-level)

Exit Codes

Environment Variables

Next: CLI Architecture → | Blueprint Actions →