Skip to main content

moai init Initialization

UPDATED 2026-10-04 3 min read EDIT ON GITHUB ↗

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]
PatternBehavior
moai init <name>Create a ./<name>/ folder and initialize inside it
moai init .Initialize in the current directory
moai initInitialize in the current directory (same as moai init .)

Accepts at most 1 argument.

Key Flags

Deployment scope

FlagDescription
--allA full local deploy: every catalog tier locally (the --no-plugin payload plus optional packs). The default without it is core-only slim mode
--no-pluginSkip 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
--forceRe-initialize an existing project (backs up the current .moai/)
--no-hooksSkip 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

FlagDescription
--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-interactiveSkip the interactive wizard — use flags and defaults only

Wizard question flags

FlagDescription
--enable-lspEnable LSP integration (default: true)
--enforce-qualityEnforce quality gates (default: true)
--enable-designEnable the design workflow (default: true)

Git / model policy

FlagDescription
--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 folder
moai init my-app

# Initialize in the current directory
moai init .

# Specify a methodology
moai init --mode tdd

# Deploy the full catalog (bypass slim mode)
moai init --all

# Non-interactive (e.g. CI)
moai init . --non-interactive --language go
CommandDescription
moai updateSync templates for an initialized project
moai statusCheck initialization status
moai doctorValidate the environment after initialization

See also