CLI Overview

A high-level overview of every command and flag of moai (the Go binary) that you run in the terminal. It is a completely different tool from /moai (the slash subcommand) that you type in the Claude Code chat — this page covers only the terminal CLI.

For the detailed per-command reference (flags, subcommands, examples), see the CLI Reference section.

moai --help

The moai CLI is divided into three groups.

Use moai version to check the currently installed version.

moai version

╭────────────────────────╮
│                        │
│    moai-adk v3.0.0     │
│                        │
│                        │
╰────────────────────────╯
 v3.0.0   none   built unknown

The line below the box banner shows <version> <commit hash> built <build time> in order. When built without ldflags (e.g. via go install), the commit shows none and the build time shows unknown.

Initializes a project. An interactive wizard configures language, Git automation, model policy, harness profile, and more.

moai init [project-name] [OPTIONS]

# Initialize a new project (interactive wizard)
moai init my-project

# Install into an existing folder
cd my-existing-project
moai init

# Non-interactive (CI/CD)
moai init --non-interactive

For detailed wizard steps, see the Initial Setup page.

Updates MoAI-ADK to the latest version. Run without flags, it refreshes both the binary and the templates, and your custom assets are preserved automatically.

moai update [OPTIONS]

# Default update (binary + templates)
moai update

# Only check whether a new version exists
moai update --check

# Re-run the configuration wizard
moai update -c

# Sync templates only
moai update --templates-only

For the detailed update procedure, see the Update page.

Runs system diagnostics. It checks Git, the project structure, configuration files, and language-specific development tools.

moai doctor [OPTIONS]

# Full diagnostics
moai doctor

# Detailed diagnostics
moai doctor --verbose

# Export diagnostic results
moai doctor --export diagnostics.json

Shows the project status at a glance. It displays whether the project is initialized, the SPEC count, and the number of configuration files.

moai status

It is a read-only command with no flags. For detailed output, see the Project Status page.

A read-only command that shows a unified view of active sessions, worktrees, and harnesses.

moai inventory [OPTIONS]

For the detailed JSON schema and usage examples, see the moai inventory page.

Manages Claude Code configuration profiles. Each profile keeps independent model, language, and display settings.

moai profile [COMMAND]

Specify a profile at launch with the -p flag:

moai cc -p work       # Run Claude with the work profile
moai glm -p cost-save # Run GLM with the cost-save profile

For more details, see the Profile Management page.

A dispatcher that handles Claude Code hook events. It is called in the form moai hook <event> from the hook configuration in settings.json.

moai hook <event>

The moai hook dispatcher provides 42 subcommands, combining the standard Claude Code hook events and MoAI-specific internal actions. All names are kebab-case. Below are the representative events.

Hook-event count and subcommand count are different numbers. The 30 reported by moai doctor hook are the hook event types Claude Code defines; the 42 here are the subcommands moai hook accepts. They do not match because MoAI-specific internal actions exist as subcommands without a corresponding event.

MoAI-specific subcommands are also included.

You do not run hooks directly — Claude Code’s settings.json calls them automatically.

Manages Git worktrees for parallel SPEC development.

moai worktree <COMMAND> [ARGS]...

Entering a worktree is the launcher’s job. For listing, use git directly.

moai cc -w feat-login           # start working in a worktree (created if missing)
moai cc -w feat-login --spawn   # open it in a new tmux window, keeping the current session
git worktree list               # list worktrees

moai cc and moai glm launch Claude Code with an explicitly selected backend. Legacy CG configurations require migration before launch.

moai cc [-p profile] [-- claude-args...]
moai glm [-p profile] [-- claude-args...]

moai cg has been retired. It exits with a migration diagnostic without starting Claude or GLM. It is not an alias for moai cc. Projects with llm.team_mode: cg must make an explicit migration choice before launching a session. CG retirement and migration

Flags common to both launch commands.

moai cc additionally supports these flags.

The auto permission mode is not available on GLM (a third-party provider) — it is supported only in moai cc.

moai cc looks for the session model in the order below and passes the first value it finds to Claude Code as --model.

1. An explicit --model argument
2. The profile’s model (the value chosen in moai profile setup)
3. The ANTHROPIC_MODEL environment variable (this launch only)
4. The model in the project’s .claude/settings.local.json (this project only)
5. The value saved with /model in that profile’s user-scope settings.json — the launch prints a one-line notice such as model: opus (user /model)
6. If all of the above are empty, nothing is passed. The project’s .claude/settings.json model pin then decides the session model, and the launcher names that value and how to change it

The more specific and more recent choice wins. Claude Code applies steps 3 and 4 itself, so the launcher passes no --model and stays out of their way. Project settings outrank user-scope settings, so without step 5 a model picked with /model would be hidden behind the project pin. moai glm does not follow this rule: GLM needs the model as a slot alias, and a value picked with /model on an Anthropic account names a different model family that would route to the wrong slot.

Registers, queries, and clears a condition-based autonomous goal loop for the current session. It is evaluated at the end of each turn until the condition is met.

moai goal <COMMAND>

Manages the auto-resume handoff pending record for continuing a session across the /clear boundary.

moai handoff <COMMAND>

Manages the active-session coordination registry for multi-session race mitigation.

moai session <COMMAND>

Launches the MoAI Web Console, a browser-based configuration editor.

moai web [OPTIONS]

Shows the version, commit hash, and build date.

moai version
moai --version    # identical

The former per-agent performance-tier system is retired. Since v3.2, subagents inherit the main session’s model and effort — pass neither model nor effort when spawning a subagent, and MoAI agent definitions declare neither. What remains of the model policy is one session-level choice: the Session model policy question in moai profile setup sets the default reasoning effort of the Claude session launched with the profile, used when no effort level is chosen.

# Configure the session model policy (and everything else about a profile)
moai profile setup

# The retired per-agent flags print a deprecation warning and do nothing
moai init my-project --model-policy high

The old --model-policy, --profile, --high, --medium-alias, and --low flags are deprecated stubs: values are accepted for script compatibility, have no effect, and print a warning pointing at moai profile setup. For the session-level model and effort controls, see the Model Policy page; for how the matrix was retired, Profile Matrix.

• Quick Start
• Installation
• Update
• Initial Setup
• Profile Management
• Project Status