moai init initializes a MoAI project in the current directory or a new folder. It lays down the .claude/ and .moai/ structure and settings required for Claude Code integration, and — when needed — configures the project mode, language, and quality gates through an interactive wizard.
Usage
bash
moai init [project-name]
Pattern
Behavior
moai init <name>
Create a ./<name>/ folder and initialize inside it
moai init .
Initialize in the current directory
moai init
Initialize in the current directory (same as moai init .)
Accepts at most 1 argument.
Key Flags
Deployment scope
Flag
Description
--all
A full local deploy: every catalog tier locally (the --no-plugin payload plus optional packs). The default without it is core-only slim mode
--no-plugin
Skip the moai plugin and deploy the FULL local payload (skills, commands, the .mcp.json moai entry, the Codex mirror). Also MOAI_SKIP_PLUGIN_INSTALL=1. On the default (plugin) path no local skills or commands deploy — the moai plugin carries them
--force
Re-initialize an existing project (backs up the current .moai/)
--no-hooks
Skip git hook installation
--llm <claude|codex|both>
Select the LLM harness to wire (default: claude)
The resolved deploy mode is recorded as deployment_mode in .moai/config/sections/llm.yaml (plugin or local), and moai update keeps the same scope per that record. A project whose plugin install could not be demonstrated is recorded on the safe side, as local.
Project defaults
Flag
Description
--root <dir>
Project root (default: current directory)
--name <name>
Project name (default: directory name)
--language <lang>
Primary programming language
--framework <name>
Framework (default: auto-detect or none)
--mode <ddd|tdd>
Development methodology (default: tdd)
--non-interactive
Skip the interactive wizard — use flags and defaults only
Wizard question flags
Flag
Description
--enable-lsp
Enable LSP integration (default: true)
--enforce-quality
Enforce quality gates (default: true)
--enable-design
Enable the design workflow (default: true)
Git / model policy
Flag
Description
--git-mode <manual|personal|team>
Git workflow mode (default: manual)
--git-provider <github|gitlab>
Git provider
--github-username <name>
GitHub username (required for personal/team mode)
--profile <high|medium|low>
Model+effort profile — stored in profile of llm.yaml (selects the profile matrix column). The legacy value max is accepted as input and normalized to high
--model-policy <high|medium|low>
Legacy performance tier — stored in performance_tier of llm.yaml (read as an alias when profile is absent)
Examples
bash
# Initialize in a new foldermoai init my-app
# Initialize in the current directorymoai init .
# Specify a methodologymoai init --mode tdd
# Deploy the full catalog (bypass slim mode)moai init --all
# Non-interactive (e.g. CI)moai init . --non-interactive --language go