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 --project-mode personal --model-policy medium

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
moai cg -p team       # Run CG mode with the team 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

Launch commands that start Claude Code while choosing the backend. All three support the -p <profile> flag to specify a profile. Passing arguments after -- straight through to Claude Code is supported only by moai cc and moai glm (moai cg does not support it).

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

moai cg activates CG mode (a Claude leader + GLM teammates). It must be run inside a tmux session, and it injects the GLM environment variables into the tmux session while the leader pane uses the Claude API. moai cg starts Claude Code directly in the current pane after setup, so there is no separate claude launch step.

# 1. Save your GLM API key (once)
moai glm setup sk-your-glm-api-key

# 2. Activate CG mode (run inside tmux — Claude Code starts directly in the current pane)
moai cg

For detailed CG mode guidance, see Introduction — Save tokens with GLM.

Flags common to all three 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 or moai cg.

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

MoAI-ADK provides a performance-tier system that assigns the optimal AI model to each agent — the starting point of Tokenomics. It is set via the performance_tier field in llm.yaml, chosen with the --model-policy flag or the initialization wizard.

# Set at initialization
moai init my-project --model-policy high

# Reconfigure an existing project
moai update -c

The profile (profile: high/medium/low) selects the active column of the profile matrix, determining each agent’s model+effort. For the detailed per-agent mapping, see the Profile Matrix page.

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