Update

A guide to keeping MoAI-ADK up to date. A single moai update refreshes both the binary and the templates, and the custom assets you created are preserved automatically.

Run without flags, it refreshes both the binary and the templates — this is the default behavior.

moai update

flowchart TD
    A["moai update runs"] --> B["Stage 1: check package version"]
    B --> C{"Latest version?"}
    C -->|"Yes"| D["Stage 2: compare config versions"]
    C -->|"No"| E["Already up to date"]
    D --> F{"Config format changed?"}
    F -->|"Yes"| G["Migrate config (after backup)"]
    F -->|"No"| H["Keep config"]
    G --> I["Stage 3: sync templates"]
    H --> I
    I --> J["Completion report"]

Compares the currently installed version with the latest version on GitHub Releases.

# Check the current version
moai --version

# Only check for available updates (no actual update)
moai update --check

The binary download in moai update cannot bypass checksum verification. If the download or parsing of the release’s checksums.txt fails, the update flow is aborted — it does not attempt the binary download.

The checksums.txt download is retried 3 times with exponential backoff:

If all retries fail, a message like the following is printed:

error: checksum unavailable: persistent retry failure after 3 attempts

There is no bypass option such as --skip-checksum (an intended CWE-345 policy).

1. Check network connectivity:
   bash Copy

   curl -I https://github.com/modu-ai/moai-adk/releases/latest

2. Check proxy / firewall — whether the GitHub release asset domains (github.com, objects.githubusercontent.com) are allowed
3. Possible temporary GitHub CDN outage — retry after a while
4. Manual binary install (if permanently blocked):
   bash Copy

   curl -fsSL https://adk.mo.ai.kr/install.sh | bash

   For a manual install, it is recommended to verify the release’s checksums.txt separately.

For the detailed threat model, see Security Notes — CWE-345.

Checks the format and compatibility of the configuration files. When the format has changed, it backs up automatically and then migrates.

Files checked:

• YAML files under .moai/config/sections/

Info

The .moai/config/ directory is always backed up before a config migration.

Syncs the project templates and default files to the latest version. Files you modified are preserved, and on conflict with the new version they are backed up and merged.

graph TD
    A["Template sync"] --> B["SKILL.md templates"]
    A --> C["Agent templates"]
    A --> D["Rule files"]
    A --> E["Config defaults"]

    B --> F{"User changes?"}
    C --> F
    D --> F
    E --> F

    F -->|"No"| G["Auto update"]
    F -->|"Yes"| H["3-way merge after backup"]

    G --> I["Sync complete"]
    H --> I

Update only the binary without syncing templates:

moai update --binary

moai update --version <tag> installs a specific GitHub release tag — stable, release-candidate (rc), or a previous version — through the same checksum-verified download path as the default update. It covers three use cases in one flag: pin to a known-stable version, switch to an rc for testing, or roll back to a previous version after a regression.

# Pin to a stable release
moai update --version v3.0.0

# The leading "v" is optional
moai update --version 3.0.0

# Try a release candidate
moai update --version v3.1.0-rc1

# Roll back to a previous version
moai update --version v2.14.0

Info

The flag stays on the api.github.com host on https and verifies the downloaded binary against the release’s published checksum — there is no --skip-checksum / --insecure bypass. A tag with no matching binary asset for your platform, or a checksum mismatch, exits non-zero and leaves the filesystem untouched.

--version is mutually exclusive with a few flags and permitted with others:

When the requested tag is older than the running version, moai update prompts for confirmation on an interactive terminal. Pass --yes (or run with a non-TTY stdin, e.g. in CI) to skip the prompt and proceed.

The default moai update (no --version) fetches GitHub’s /releases/latest, which automatically excludes pre-releases — so rc and pre-release tags are never surfaced by the default flow. --version <tag> is the only way to install an rc or a specific previous tag explicitly.

Sync only the templates without updating the binary:

moai update --templates-only

Re-run the configuration wizard to change the project setup (does not perform a template sync):

moai update -c
# or
moai update --config

Preview the planned archive and install actions without making any actual changes:

moai update --dry-run

Auto-approve all confirmations:

moai update --yes

moai --version

moai doctor

moai --help

On a MoAI-ADK update, CLAUDE.md and settings.json are synced to the new version. Keep your personal modifications in separate files.

Info

Settings priority: Local > Project > User > Enterprise
settings.local.json overrides the project settings.

MoAI-ADK manages files only in the following folders:

.claude/
├── agents/
│   ├── moai/                # MoAI-ADK agents (update target)
│   └── harness/             # User harness agents (excluded from update, preserved)
│
├── hooks/
│   └── moai/                # MoAI-ADK hook scripts (update target)
│
├── skills/
│   ├── moai-*               # MoAI-ADK skills (moai- prefix, update target)
│   └── hns-*                # User-created skills (excluded from update, preserved)
│
└── rules/
    └── moai/                # Rule files (moai managed)

Warning

Important: Skills with the moai- prefix are managed by MoAI-ADK and are overwritten on update. For skills you create yourself, use the hns- prefix (the user-owned namespace), and for agents use the .claude/agents/harness/ directory.

If a problem occurs after an update, you can roll back to a previous version:

# Roll back to a specific version in-process (recommended)
moai update --version <release-tag>

# Bootstrap path (before moai is installed): use the install script
curl -fsSL https://adk.mo.ai.kr/install.sh | bash -s -- --version <release-tag>

# Restore the config from backup
cp -r .moai/config.bak .moai/config

Warning

Commit your current work before rolling back.

# Check the network
curl -I https://github.com/modu-ai/moai-adk/releases/latest

# Manual reinstall
curl -fsSL https://adk.mo.ai.kr/install.sh | bash

# Restore from backup
cp -r .moai/config.bak .moai/config

# Validate the config
moai doctor

Template files you modified are backed up automatically and then 3-way merged. If a conflict occurs, check the detailed warnings with --verbose:

moai update --verbose

To force an overwrite, use --force (your existing changes are backed up to .moai/archive/):

moai update --force

1. Check the changelog — learn the new features
2. Core Concepts — master the new agents and features
3. Quick Start — apply the new features to your project