Skip to main content

​
arckit init

The arckit init command creates a new ArcKit project with a complete directory structure, governance templates, and AI assistant integration.
This is a CLI command (not a slash command). Run it directly in your terminal before starting your AI assistant.

​
Description

Initializes a new ArcKit project for enterprise architecture governance by:
  1. Creating project directory structure
  2. Copying templates for architecture principles, requirements, SOW, etc.
  3. Setting up AI assistant commands (Codex or OpenCode)
  4. Copying documentation and guides (unless --minimal)
  5. Initializing git repository (optional)

​
Usage

arckit init [PROJECT_NAME] [OPTIONS]

​
Basic Examples

# Create new project directory
arckit init my-architecture-project

# Initialize in current directory
arckit init . --ai codex
arckit init --here --ai codex

# Create with specific AI assistant
arckit init my-project --ai codex

# Minimal install (skip docs)
arckit init my-project --ai codex --minimal

# Skip git initialization
arckit init my-project --ai codex --no-git

​
Arguments

​
PROJECT_NAME
string
Name for your new project directory. Use . or --here to initialize in the current directory.Examples:
  • my-architecture-project
  • . (current directory)
  • uk-gov-digital-service

​
Options

​
--ai
string
default:"interactive"
AI assistant to configure for slash command integration.Choices:
  • codex - OpenAI Codex CLI
  • opencode - OpenCode CLI
For Claude Code, use the ArcKit plugin instead:
/plugin marketplace add tractorjuice/arc-kit
For Gemini CLI, use the ArcKit extension:
gemini extensions install https://github.com/tractorjuice/arckit-gemini
​
--here
boolean
default:"false"
Initialize project in the current directory instead of creating a new one.Example:
arckit init --here --ai codex
​
--no-git
boolean
default:"false"
Skip git repository initialization.Example:
arckit init my-project --ai codex --no-git
​
--minimal
boolean
default:"false"
Minimal install: skip documentation and guides. Only installs templates and commands.Example:
arckit init my-project --ai codex --minimal
​
--all-ai
boolean
default:"false"
Install commands for all CLI-supported AI assistants (Codex and OpenCode).Example:
arckit init my-project --all-ai

​
Prerequisites

ArcKit requires Python 3.11 or later.
python --version  # Should show 3.11 or higher
direnv automatically loads environment variables when entering the project directory.
# Install direnv (macOS)
brew install direnv

# Add to shell (bash)
echo 'eval "$(direnv hook bash)"' >> ~/.bashrc

# Add to shell (zsh)
echo 'eval "$(direnv hook zsh)"' >> ~/.zshrc
After arckit init, run:
direnv allow

​
What It Creates

​
Directory Structure

my-architecture-project/
├── .arckit/
│   ├── scripts/
│   │   └── bash/              # Automation helpers
│   ├── templates/             # Default templates (refreshed by arckit init)
│   └── templates-custom/      # Your customizations (preserved across updates)
├── projects/
│   ├── 000-global/
│   │   ├── policies/          # Enterprise standards
│   │   └── external/          # Reference documents
│   └── 001-project-name/      # Created by /arckit.plan
├── .codex/                    # Codex CLI integration (if --ai codex)
│   └── prompts/               # Slash command definitions
├── .opencode/                 # OpenCode CLI integration (if --ai opencode)
│   ├── commands/              # Slash command definitions
│   └── agents/                # Specialized agents
├── docs/
│   ├── guides/                # Command usage guides
│   └── README.md              # Documentation index
├── .envrc                     # direnv configuration
├── .gitignore                 # Git ignore patterns
├── README.md                  # Project README
├── VERSION                    # ArcKit version
├── CHANGELOG.md               # Version history
├── DEPENDENCY-MATRIX.md       # Command dependencies
└── WORKFLOW-DIAGRAMS.md       # Visual workflows

​
Generated Files

54 document templates copied to .arckit/templates/:
  • Architecture principles
  • Requirements
  • Risk register
  • Business cases
  • SOW/RFP
  • Design reviews
  • And 48 more…

​
Example Output

 █████╗ ██████╗  ██████╗██╗  ██╗██╗████████╗
██╔══██╗██╔══██╗██╔════╝██║ ██╔╝██║╚══██╔══╝
███████║██████╔╝██║     █████╔╝ ██║   ██║
██╔══██║██╔══██╗██║     ██╔═██╗ ██║   ██║
██║  ██║██║  ██║╚██████╗██║  ██╗██║   ██║
╚═╝  ╚═╝╚═╝  ╚═╝ ╚═════╝╚═╝  ╚═╝╚═╝   ╚═╝

Enterprise Architecture Governance & Vendor Procurement

Initializing ArcKit project: my-architecture-project
Location: /Users/name/my-architecture-project

Select your AI assistant:
1. codex (OpenAI Codex CLI)
2. opencode (OpenCode CLI)

Enter choice [1]: 1
Selected AI assistant: OpenAI Codex CLI

Creating project structure...
✓ Project structure created

Setting up templates...
✓ Copied 54 templates
✓ Scripts copied
✓ Copied 54 Codex prompts
✓ Templates configured

Setting up documentation...
✓ Copied 54 command guides
✓ Copied docs/README.md
✓ Copied DEPENDENCY-MATRIX.md
✓ Copied WORKFLOW-DIAGRAMS.md
✓ Documentation configured

✓ Copied VERSION
✓ Copied CHANGELOG.md
✓ README created

Initializing git repository...
✓ Git repository initialized

Setting up Codex environment...
✓ Copied .codex/README.md
✓ Copied .codex/.gitignore
✓ Codex environment configured (.envrc created)

✓ ArcKit project initialized successfully!

┌─────────────────────────────────────────────────────────────────┐
│                          Next Steps                             │
├─────────────────────────────────────────────────────────────────┤
│ 1. Navigate to project: cd my-architecture-project              │
│ 2. Set up CODEX_HOME environment variable:                      │
│    RECOMMENDED: Install direnv and run direnv allow             │
│    Alternative: Run export CODEX_HOME="$PWD/.codex"             │
│ 3. Start Codex: codex                                           │
│ 4. Establish architecture principles: /arckit.principles        │
│ 5. Create your first project: /arckit.requirements              │
└─────────────────────────────────────────────────────────────────┘

​
Next Steps

1

Navigate to Project

cd my-architecture-project
2

Set Up Environment (Recommended)

# Install direnv (if not already installed)
brew install direnv  # macOS

# Allow direnv for this project
direnv allow
Or manually set environment variable:
export CODEX_HOME="$PWD/.codex"  # For Codex
export OPENCODE_HOME="$PWD/.opencode"  # For OpenCode
3

Start Your AI Assistant

codex      # For Codex CLI
opencode   # For OpenCode CLI
4

Establish Architecture Principles

/arckit.principles
This creates projects/000-global/ARC-000-PRIN-v1.0.md — the governance foundation required by most downstream commands.
5

Create Your First Project

/arckit.plan        # Create project plan
/arckit.stakeholders # Analyze stakeholders
/arckit.requirements # Define requirements

​
Customizing Templates

After initialization, customize templates using the /arckit.customize command: 
# List available templates
/arckit.customize list

# Copy requirements template for editing
/arckit.customize requirements

# Copy all templates
/arckit.customize all
Customized templates are stored in .arckit/templates-custom/ and preserved when running arckit init again.

​
Updating an Existing Project

Running arckit init again in an existing project:
Templates in .arckit/templates/ are updated to the latest version.
Your custom templates in .arckit/templates-custom/ are never modified.
Slash commands in .codex/prompts/ or .opencode/commands/ are refreshed.
Guides, diagrams, and reference docs are updated to match the new version.

​
Troubleshooting

Error: Directory 'my-project' already exists
Solution: Use a different project name or use --here to initialize in the current directory:
arckit init --here --ai codex

Git not found - will skip repository initialization
Solution: Install git or use --no-git flag:
arckit init my-project --ai codex --no-git
Codex CLI:
  1. Verify CODEX_HOME is set: 
    echo $CODEX_HOME  # Should show /path/to/project/.codex
  2. Restart Codex after setting CODEX_HOME
OpenCode CLI:
  1. Verify OPENCODE_HOME is set: 
    echo $OPENCODE_HOME  # Should show /path/to/project/.opencode
  2. Restart OpenCode after setting OPENCODE_HOME

arckit check

Verify ArcKit installation and prerequisites

/arckit.start

Get oriented with guided onboarding

/arckit.principles

Create architecture principles

/arckit.customize

Customize document templates

Build docs developers (and LLMs) love

Get started for freeTalk to us