mops-cli

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Mops CLI

Mops CLI

Opinionated guide for Motoko projects. Covers project config, dependency management, type-checking, building, and linting.
面向 Motoko 项目的强约定指南。涵盖项目配置、依赖管理、类型检查、构建和 lint。

Key Principles

关键原则

  1. No dfx — mops neither invokes nor supports
    dfx
    . There is no
    mops toolchain init
    , no
    moc-wrapper
    , and no
    mops watch --generate
    /
    --deploy
    . Always pin
    moc
    in
    [toolchain]
    ; every command that compiles requires it. Use the newest
    moc
    version. Pin
    pocket-ic
    too if you have replica tests, benchmarks, or
    --check-deploy
    — with no pin those commands error, naming
    mops toolchain use pocket-ic 15.0.0
    . When
    MOPS_POCKET_IC_URL
    points at an already-running PocketIC server, no pin is needed and an existing pin is ignored with a warning — do not add one to silence it; unset the variable instead.
  2. No
    mo:base
    — it is deprecated. Always use
    mo:core
    (
    import Array "mo:core/Array"
    ).
  3. All config in
    mops.toml
    — canisters, moc flags, toolchain versions, build settings.
  4. Canister-centric workflow — define all canisters in
    [canisters]
    ; never pass file paths to
    mops check
    . Exception: library packages (no
    [canisters]
    ) use file paths directly:
    mops check src/**/*.mo
    .
  1. 不使用 dfx — mops 既不调用也不支持
    dfx
    。不存在
    mops toolchain init
    、没有
    moc-wrapper
    ,也不存在
    mops watch --generate
    /
    --deploy
    。始终在
    [toolchain]
    中锁定
    moc
    ;每个会进行编译的命令都需要它。使用最新的
    moc
    版本。如果有 replica 测试、benchmark 或
    --check-deploy
    ,也应锁定
    pocket-ic
    ;未锁定时,这些命令会报错并提示
    mops toolchain use pocket-ic 15.0.0
    。当
    MOPS_POCKET_IC_URL
    指向已经运行的 PocketIC 服务器时,无需锁定,已有锁定会被忽略并发出警告——不要为了消除警告而添加锁定;应改为取消设置该环境变量。
  2. 不使用
    mo:base
    — 它已弃用。始终使用
    mo:core
    (
    import Array "mo:core/Array"
    )。
  3. 所有配置都放在
    mops.toml
    中
    — canister、moc 标志、工具链版本和构建设置。
  4. 以 canister 为中心的工作流 — 在
    [canisters]
    中定义所有 canister;绝不要向
    mops check
    传递文件路径。例外:库软件包(没有
    [canisters]
    )可直接使用文件路径:
    mops check src/**/*.mo
    。

Project Setup

项目设置

Minimal
mops.toml

最小
mops.toml

toml
[toolchain]
moc = "1.15.1"
lintoko = "0.11.0"
pocket-ic = "15.0.0"  # required for replica tests / benchmarks / --check-deploy

[dependencies]
core = "2.6.1"

[moc]
args = ["--default-persistent-actors", "-W=M0223,M0236,M0237"]

[canisters.backend]
main = "src/backend/main.mo"

[canisters.backend.migrations]
chain = "src/backend/migrations"
toml
[toolchain]
moc = "1.15.1"
lintoko = "0.11.0"
pocket-ic = "15.0.0"  # required for replica tests / benchmarks / --check-deploy

[dependencies]
core = "2.6.1"

[moc]
args = ["--default-persistent-actors", "-W=M0223,M0236,M0237"]

[canisters.backend]
main = "src/backend/main.mo"

[canisters.backend.migrations]
chain = "src/backend/migrations"

check-limit = 10 # optional — speeds up
mops check
when the chain gets long

check-limit = 10 # optional — speeds up
mops check
when the chain gets long

[canisters.backend.check-stable] path = "deployed/backend.most"
[build] outputDir = "src/backend/dist" args = ["--release"]
[canisters.backend.check-stable] path = "deployed/backend.most"
[build] outputDir = "src/backend/dist" args = ["--release"]

check-wasm = true # optional: analyze final Wasm complexity

check-wasm = true # optional: analyze final Wasm complexity

check-deploy = true # optional: verify fresh PocketIC installation after build

check-deploy = true # optional: verify fresh PocketIC installation after build

Opt-in Wasm optimization (Binaryen wasm-opt) for build + bench

Opt-in Wasm optimization (Binaryen wasm-opt) for build + bench

[optimize]
[optimize]

level = "O3" # default

level = "O3" # default

keep-names = true # default

keep-names = true # default

wasm-opt pin: [toolchain] wasm-opt = "131" (required when [optimize] is set)

wasm-opt pin: [toolchain] wasm-opt = "131" (required when [optimize] is set)


`check-stable` runs ICP's upgrade-time stable-variable compatibility check locally, so incompatible changes fail in `mops check` instead of being rejected when upgrading a live canister. It compares the current code against a `.most` from the deployed version.

Bootstrap that `.most`: new project → `mops deployed init` (empty-actor baseline); already-deployed canister → build from the deployed commit, then `mops deployed`. After every deploy, run `mops deployed` to promote the just-built `.most` (see [`mops deployed`](#mops-deployed) below).

Optional canister fields: `candid` (path to .did for compatibility checking), `initArg` (Candid-encoded init args).

`check-stable` 会在本地运行 ICP 的升级时 stable-variable 兼容性检查,因此不兼容的更改会在 `mops check` 阶段失败,而不是在升级线上 canister 时才被拒绝。它会将当前代码与已部署版本的 `.most` 进行比较。

初始化该 `.most`:新项目 → `mops deployed init`(空 actor 基线);已部署的 canister → 从已部署的提交构建,然后执行 `mops deployed`。每次部署后,运行 `mops deployed`,将刚构建的 `.most` 提升为基线(参见下方的 [`mops deployed`](#mops-deployed))。

可选的 canister 字段:`candid`(用于兼容性检查的 `.did` 路径)、`initArg`(Candid 编码的初始化参数)。

Warning Flags

警告标志

-W=M0223,M0236,M0237
— redundant type instantiation (M0223), suggest contextual dot notation (M0236), suggest redundant explicit arguments (M0237). These are allowed (disabled) by default;
-W=
enables them as warnings.
-W=M0223,M0236,M0237
— 冗余类型实例化(M0223)、建议使用上下文点表示法(M0236)、建议移除冗余显式参数(M0237)。默认情况下,这些诊断项处于禁用状态;
-W=
会将其启用为警告。

Moc Args Layering

Moc 标志分层

Flags are applied in this order (later overrides earlier):
  1. [moc].args
    — global, all commands (check, build, test, bench, etc.)
  2. [build].args
    — build only (e.g.
    --release
    )
  3. [canisters.<name>.migrations]
    — auto-injected
    --enhanced-migration
    (managed by mops)
  4. [canisters.<name>].args
    — per-canister
  5. CLI
    -- <flags>
    — one-off overrides; supported by
    mops check
    ,
    mops build
    ,
    mops check-stable
    ,
    mops generate
    ,
    mops migrate
    ,
    mops test
    , and
    mops bench
标志按以下顺序应用(后面的覆盖前面的):
  1. [moc].args
    — 全局,适用于所有命令(check、build、test、bench 等)
  2. [build].args
    — 仅用于构建(例如
    --release
    )
  3. [canisters.<name>.migrations]
    — 自动注入
    --enhanced-migration
    (由 mops 管理)
  4. [canisters.<name>].args
    — 按 canister 设置
  5. CLI
    -- <flags>
    — 一次性覆盖;
    mops check
    、
    mops build
    、
    mops check-stable
    、
    mops generate
    、
    mops migrate
    、
    mops test
    和
    mops bench
    均支持

Core Commands

核心命令

mops install

mops install

bash
mops install            # dev flow: keeps mops.lock in sync, self-heals a broken one
mops install --locked   # CI flow: fail if mops.lock is missing or would change
Run after cloning or after manual
mops.toml
edits.
mops.lock
is always maintained — there is no flag to opt out, and no
--lock
flag (removed in v3). A missing, unparseable, legacy-format or
mops.toml
-inconsistent lock is regenerated by a plain
mops install
, including locks that still carry absolute local paths from older CLIs, and locks that lost a transitive dependency (a locked package declares a dependency that
deps
no longer lists — typically a botched merge).
--locked
requires an up-to-date lock and never writes it. It is also available on every implicitly-installing command (
mops build
,
mops check
,
mops check-stable
,
mops check-candid
,
mops test
,
mops bench
,
mops generate candid
), so CI can run
mops test --locked
with no prior install.
mops sources
has no
--locked
(a packtool caller parses its stdout mid-build) — put
mops install --locked
earlier in the pipeline instead.
The
CI
env var no longer affects lockfile behavior (removed in v3). Commit
mops.lock
— for applications and libraries alike.
A lock also goes stale when a local
path
dependency's own
mops.toml
changes — including one nested further down the chain.
mops install
regenerates it;
--locked
fails until the regenerated lock is committed. Note the first
mops install
after upgrading regenerates the lock of any project that has a
path
dependency, so commit it before running
--locked
in CI. Projects without
path
dependencies keep their existing lock.
{MOPS_ENV}
in a
path
dependency expands to
$MOPS_ENV
(default
local
), which makes the lock environment-specific. Switching
MOPS_ENV
makes it stale:
mops install
regenerates it, and
--locked
fails with a message naming
MOPS_ENV
. Keep one lock per environment, or drop
--locked
— a lock generated under one
MOPS_ENV
will not satisfy
--locked
under another.
Integrity is verified at download time, so
mops install
no longer re-hashes
.mops/
: editing a dependency in place will not fail the next install. Use
mops verify
for the on-demand on-disk audit.
Downloaded files are always checked before anything enters the cache — against
mops.lock
when it already records the package, otherwise against the registry. A committed lock therefore makes verification free, which is why a clean checkout installs without asking the registry about hashes.
Two consequences worth knowing: a corrupt or hand-edited
mops.lock
now fails a download (the error names
mops.lock
as a possible culprit — restore it from version control; already-cached packages are unaffected), and a package the registry publishes no hashes for still installs, unverified, with a warning.
Packages download in parallel through a bounded pool.
mops install --concurrency <n>
or the
MOPS_CONCURRENCY
env var (works on every installing command) caps simultaneous registry requests; the default derives from the CPU count and the file-descriptor soft limit (4–16). Transient network errors (
fetch failed
,
ECONNRESET
,
EMFILE
) retry automatically with the concurrency halved, up to twice. Set
MOPS_CONCURRENCY=1
only if installs still fail after the retries (an egress proxy capping connections, for example).
bash
mops install            # dev flow: keeps mops.lock in sync, self-heals a broken one
mops install --locked   # CI flow: fail if mops.lock is missing or would change
克隆仓库或手动编辑
mops.toml
后运行。
mops.lock
始终会被维护——没有选择退出的标志,也没有
--lock
标志(v3 中已移除)。如果锁文件缺失、无法解析、采用旧格式,或与
mops.toml
不一致,普通的
mops install
会重新生成它;这包括仍携带旧版 CLI 绝对本地路径的锁文件,以及丢失传递依赖的锁文件(已锁定的软件包声明了
deps
中不再列出的依赖,通常由错误合并导致)。
--locked
要求锁文件为最新状态,且绝不会写入它。每个会隐式安装的命令(
mops build
、
mops check
、
mops check-stable
、
mops check-candid
、
mops test
、
mops bench
、
mops generate candid
)也支持该选项,因此 CI 可以在不预先安装的情况下运行
mops test --locked
。
mops sources
不支持
--locked
(packtool 调用方会在构建过程中解析其标准输出)——应在流水线更早的位置执行
mops install --locked
。
CI
环境变量不再影响锁文件行为(v3 中已移除)。无论是应用还是库,都应提交
mops.lock
。
当本地
path
依赖项自身的
mops.toml
发生变化时,锁文件也会失效——包括依赖链更深处嵌套的
path
依赖。
mops install
会重新生成锁文件;
--locked
则会失败,直到重新生成的锁文件被提交。升级后第一次执行
mops install
时,任何包含
path
依赖的项目都会重新生成锁文件,因此请在 CI 中运行
--locked
前先提交它。没有
path
依赖的项目会保留现有锁文件。
path
依赖项中的
{MOPS_ENV}
会展开为
$MOPS_ENV
(默认值为
local
),这会使锁文件与环境相关。切换
MOPS_ENV
后,锁文件会失效:
mops install
会重新生成它,而
--locked
会报错并指出
MOPS_ENV
。请为每个环境维护一份锁文件,或者不要使用
--locked
——在某个
MOPS_ENV
下生成的锁文件无法在另一个环境下满足
--locked
。
完整性会在下载时验证,因此
mops install
不再重新计算
.mops/
的哈希;就地编辑依赖项不会导致下次安装失败。如需按需审计磁盘内容,请使用
mops verify
。
下载的文件在进入 cache 前总会接受检查——如果
mops.lock
已记录该软件包,则依据
mops.lock
检查,否则依据 registry 检查。因此,提交锁文件后校验便无需额外成本,这也是干净检出的环境无需向 registry 查询哈希即可完成安装的原因。
有两个值得了解的后果:损坏或手工编辑过的
mops.lock
现在会导致下载失败(错误信息会将
mops.lock
列为可能原因——应从版本控制中恢复;已缓存的软件包不受影响);registry 未发布任何哈希的软件包仍会安装,但无法验证,并发出警告。
软件包通过设有上限的并发池并行下载。
mops install --concurrency <n>
或
MOPS_CONCURRENCY
环境变量(适用于所有安装命令)可限制同时发往 registry 的请求数;默认值根据 CPU 数量和文件描述符软限制计算(4–16)。暂时性网络错误(
fetch failed
、
ECONNRESET
、
EMFILE
)会自动重试,并将并发数减半,最多重试两次。仅当重试后安装仍失败时才设置
MOPS_CONCURRENCY=1
(例如出口代理限制了连接数)。

mops verify

mops verify

bash
mops verify   # re-hash .mops/ against mops.lock, and mops.lock against the registry
Covers GitHub dependencies as well as registry ones.
Exits 1 with the offending files and a recovery hint. This is the replacement for anyone who relied on
mops install
failing when
.mops/
had been modified.
bash
mops verify   # re-hash .mops/ against mops.lock, and mops.lock against the registry
它同时覆盖 GitHub 依赖项和 registry 依赖项。
命令会以状态码 1 退出,并列出违规文件和恢复提示。它取代了依赖
mops install
在
.mops/
被修改时失败这一旧行为。

mops add <package>

mops add <package>

bash
mops add core             # latest version
mops add core@2.5.0       # specific version
mops add --dev test       # dev dependency
mops add org/repo         # GitHub shorthand (also accepts a full github.com url)
mops add ./pkg            # local package directory
Updates
mops.toml
and
mops.lock
.
Adding a package that is already declared in the other section moves it rather than declaring it twice.
<pkg>@<version>
replaces the declared version and reports what it replaced; it leaves pinned aliases like
"core@1.0.0" = "1.0.0"
alone, and there is no flag to create one — write it by hand.
bash
mops add core             # latest version
mops add core@2.5.0       # specific version
mops add --dev test       # dev dependency
mops add org/repo         # GitHub shorthand (also accepts a full github.com url)
mops add ./pkg            # local package directory
更新
mops.toml
和
mops.lock
。
如果添加的软件包已声明在另一个区块中,它会将其移动过去,而不是重复声明。
<pkg>@<version>
会替换已声明的版本并报告替换内容;它不会改动类似
"core@1.0.0" = "1.0.0"
的固定别名,也没有用于创建别名的标志——请手动编写。

mops check

mops check

Primary correctness command — runs moc check, then check-stable (if configured), then lint (if lintoko is in toolchain).
On moc 1.15.0+, canisters with
[migrations]
get stricter upgrade diagnostics: a field the initial actor requires that no migration produces fails as an
M0267
error instead of only warning (
M0254
), and compat errors carry a source location. Older moc pins and canisters without
[migrations]
are unaffected either way.
The
check-stable
baseline is always a
.most
file — as
[canisters.<name>.check-stable].path
or as the
mops check-stable <baseline.most>
argument. A
.mo
source is rejected. See
mops deployed
for where the baseline comes from — that differs between a fresh project and an already-deployed canister.
bash
mops check                # all canisters
mops check backend        # single canister
mops check --fix          # autofix + check + stable + lint
mops check --no-lint      # skip the lint step for one run
mops check --verbose      # show moc invocations
mops check -- -Werror     # treat warnings as errors
Always use canister names, not file paths. Per-canister args from
mops.toml
are applied automatically.
--fix
applies machine-applicable fixes from both moc and lintoko in one pass. Concurrent
--fix
runs (across processes) serialize automatically via an advisory lock at
.mops/fix.lock
— safe to invoke from multiple agents on the same project. Read-only files (e.g. frozen migrations) are skipped with a warning, not fixed.
主要的正确性检查命令——运行 moc check,然后运行 check-stable(如果已配置),最后运行 lint(如果工具链中有 lintoko)。
在 moc 1.15.0 及更高版本上,带有
[migrations]
的 canister 会获得更严格的升级诊断:如果初始 actor 要求某个字段,但没有任何 migration 生成该字段,则会报
M0267
错误,而不只是警告(
M0254
);兼容性错误也会包含源代码位置。较旧的 moc 固定版本以及没有
[migrations]
的 canister 均不受影响。
check-stable
基线始终是一个
.most
文件——可以是
[canisters.<name>.check-stable].path
,也可以是
mops check-stable <baseline.most>
参数。
.mo
源文件会被拒绝。有关基线的来源,请参见
mops deployed
——新项目与已部署 canister 的处理方式不同。
bash
mops check                # all canisters
mops check backend        # single canister
mops check --fix          # autofix + check + stable + lint
mops check --no-lint      # skip the lint step for one run
mops check --verbose      # show moc invocations
mops check -- -Werror     # treat warnings as errors
始终使用 canister 名称,不要使用文件路径。
mops.toml
中的每个 canister 参数都会自动应用。
--fix
会在一次运行中应用来自 moc 和 lintoko 且可由机器执行的修复。并发
--fix
运行(跨进程)会通过
.mops/fix.lock
上的 advisory lock 自动串行化——可安全地从多个 Agent 在同一项目中调用。只读文件(例如冻结的 migration)会被跳过并给出警告,不会被修复。

mops build

mops build

bash
mops build                # all canisters
mops build backend        # single canister
mops build --verbose      # show compiler commands
mops build --check-wasm   # analyze final Wasm complexity without PocketIC
mops build --no-check-wasm # skip configured [build].check-wasm once
mops build --check-deploy  # verify fresh installation on PocketIC
mops build --no-check-deploy # skip configured [build].check-deploy once
mops build -- --ai-errors # pass extra moc flags
Produces
.wasm
,
.did
, and
.most
files in
[build].outputDir
(default
.mops/.build
).
With
[optimize]
in
mops.toml
, runs
wasm-opt
after candid metadata (default
-O3 -g
). Requires a Binaryen pin:
mops toolchain use wasm-opt 131
. Build commands never write the pin themselves, and a
wasm-opt
failure fails the build. Pass
--no-optimize
(on
build
or
bench
) to skip the pass for a single run without editing
mops.toml
.
When
--check-wasm
or
[build].check-wasm = true
is enabled, Mops runs fast Walrus analysis on the final Wasm without starting PocketIC. Per-function IC0505 complexity below 750,000 is quiet, 750,000 through 899,999 emits an early warning, and 900,000 or more emits a critical warning.
MOPS-WASM-COMPLEXITY
output includes actionable function metrics, the three largest complexity contributors, and Motoko correction guidance. The estimate never fails the build. Use
--no-check-wasm
to skip configured analysis once.
bash
mops build                # all canisters
mops build backend        # single canister
mops build --verbose      # show compiler commands
mops build --check-wasm   # analyze final Wasm complexity without PocketIC
mops build --no-check-wasm # skip configured [build].check-wasm once
mops build --check-deploy  # verify fresh installation on PocketIC
mops build --no-check-deploy # skip configured [build].check-deploy once
mops build -- --ai-errors # pass extra moc flags
在
[build].outputDir
(默认
.mops/.build
)中生成
.wasm
、
.did
和
.most
文件。
在
mops.toml
中设置
[optimize]
后,会在 candid 元数据之后运行
wasm-opt
(默认
-O3 -g
)。需要 Binaryen 固定版本:
mops toolchain use wasm-opt 131
。构建命令绝不会自行写入该固定版本,
wasm-opt
失败也会导致构建失败。若只想单次跳过此步骤,可在
build
或
bench
上传入
--no-optimize
,而无需编辑
mops.toml
。
启用
--check-wasm
或设置
[build].check-wasm = true
时,Mops 会在不启动 PocketIC 的情况下,对最终 Wasm 运行快速 Walrus 分析。单函数 IC0505 复杂度低于 750,000 时不会产生提示;750,000 到 899,999 会发出早期警告;900,000 或更高会发出严重警告。
MOPS-WASM-COMPLEXITY
输出包含可操作的函数指标、复杂度贡献最大的三个因素,以及 Motoko 修正建议。该估算永远不会导致构建失败。使用
--no-check-wasm
可单次跳过已配置的分析。

mops deployed

mops deployed

Post-deploy hook — keeps the on-disk
.most
baseline used by
check-stable
in sync with what's actually deployed.
bash
mops deployed init backend   # one-time bootstrap: empty-actor baseline + sets [check-stable].path
mops deployed backend        # post-deploy: promotes .mops/.build/backend.most → deployed/backend.most
mops deployed                # all canisters
Default destination is
deployed/<name>.most
; override with
[deployed].dir
in
mops.toml
or
--dir
. It reads built
.most
files from
[build].outputDir
(default
.mops/.build
); override with
--build-dir
.
mops deployed
errors if the source
.most
is missing — it never regenerates. Run it from your deploy pipeline immediately after a successful deploy.
部署后钩子——使
check-stable
使用的磁盘上的
.most
基线与实际部署内容保持同步。
bash
mops deployed init backend   # one-time bootstrap: empty-actor baseline + sets [check-stable].path
mops deployed backend        # post-deploy: promotes .mops/.build/backend.most → deployed/backend.most
mops deployed                # all canisters
默认目标为
deployed/<name>.most
;可通过
mops.toml
中的
[deployed].dir
或
--dir
覆盖。它从
[build].outputDir
(默认
.mops/.build
)读取已构建的
.most
文件;可通过
--build-dir
覆盖。如果源
.most
缺失,
mops deployed
会报错——它绝不会重新生成。应在部署流水线中紧接成功部署后运行。

mops generate candid

mops generate candid

bash
mops generate candid                # all canisters
mops generate candid backend        # single canister
mops generate candid backend -o <path>   # single canister, ad-hoc path
(Re)generates the curated
.did
from current Motoko source. With
[canisters.<name>].candid
set, overwrites that file. Without it, writes
<name>.did
next to
main
(e.g.
main = "src/Backend.mo"
→
src/backend.did
) and sets
[canisters.<name>].candid
in
mops.toml
. Run after every interface change; commit
.did
+
mops.toml
together. Same moc invocation as
mops build
, so the result always passes
mops build
's subtype check.
bash
mops generate candid                # all canisters
mops generate candid backend        # single canister
mops generate candid backend -o <path>   # single canister, ad-hoc path
根据当前 Motoko 源代码重新生成整理好的
.did
。设置
[canisters.<name>].candid
后,覆盖该文件;未设置时,在
main
旁写入
<name>.did
(例如
main = "src/Backend.mo"
→
src/backend.did
),并在
mops.toml
中设置
[canisters.<name>].candid
。每次接口变更后都应运行;
.did
和
mops.toml
需一起提交。其 moc 调用方式与
mops build
相同,因此结果始终能通过
mops build
的 subtype 检查。

mops toolchain

mops toolchain

bash
mops toolchain use moc 1.15.1        # pin specific version
mops toolchain use moc latest        # pin latest version (non-interactive)
mops toolchain use lintoko 0.11.0    # pin specific version
mops toolchain use pocket-ic 15.0.0  # pin for replica tests / benchmarks / --check-deploy
mops toolchain use wasm-opt 131      # Binaryen for [optimize] (or `latest`)
mops toolchain update moc            # update to latest (requires existing [toolchain] entry)
mops toolchain update                # update all tools to latest
mops toolchain info <tool>           # show release info (latest, pinned, history)
mops toolchain info <tool> --versions # list recent releases, newest first
mops toolchain info <tool> --versions --all # full release history (cache warming)
mops toolchain info <tool> --versions --prerelease # include prereleases
mops toolchain bin moc               # print path to binary
pocket-ic
versions
: pin anything from
9.0.0
up,
latest
included — mops keeps no list of blessed versions. Pins below
9.0.0
error with a migration message (they ran on the legacy client that mops 3.0.0 removed). With no pin, replica tests /
mops bench
/
--check-deploy
/
mops toolchain bin pocket-ic
error naming
mops toolchain use pocket-ic 15.0.0
. That version is a hint, not a fallback.
Agent note:
toolchain use <tool>
without a version opens an interactive picker — do not use in scripts or agents. Always pass a version or
latest
. The picker,
latest
, and
--versions
all default to stable releases; pass
--prerelease
to include prereleases.
toolchain update
only works when the tool already has a
[toolchain]
entry.
toolchain info <tool> --versions
works without
mops.toml
(first GitHub page by default; pass
--all
for full history).
bash
mops toolchain use moc 1.15.1        # pin specific version
mops toolchain use moc latest        # pin latest version (non-interactive)
mops toolchain use lintoko 0.11.0    # pin specific version
mops toolchain use pocket-ic 15.0.0  # pin for replica tests / benchmarks / --check-deploy
mops toolchain use wasm-opt 131      # Binaryen for [optimize] (or `latest`)
mops toolchain update moc            # update to latest (requires existing [toolchain] entry)
mops toolchain update                # update all tools to latest
mops toolchain info <tool>           # show release info (latest, pinned, history)
mops toolchain info <tool> --versions # list recent releases, newest first
mops toolchain info <tool> --versions --all # full release history (cache warming)
mops toolchain info <tool> --versions --prerelease # include prereleases
mops toolchain bin moc               # print path to binary
pocket-ic
版本
:可以锁定
9.0.0
及以上的任意版本,也包括
latest
——mops 不维护一份受认可版本列表。固定为
9.0.0
以下版本会报错并给出迁移提示(它们依赖 mops 3.0.0 已移除的旧版客户端)。未固定版本时,replica 测试 /
mops bench
/
--check-deploy
/
mops toolchain bin pocket-ic
会报错并提示
mops toolchain use pocket-ic 15.0.0
。该版本只是提示,不是 fallback。
Agent 提示:不带版本执行
toolchain use <tool>
会打开交互式选择器——不要在脚本或 Agent 中使用。始终传入版本或
latest
。选择器、
latest
和
--versions
默认都只包含稳定版;传入
--prerelease
可包含预发布版本。
toolchain update
仅在工具已有
[toolchain]
条目时有效。
toolchain info <tool> --versions
无需
mops.toml
即可使用(默认获取 GitHub 第一页;传入
--all
获取完整历史)。

Enhanced migrations

增强型 migration

When
[canisters.<name>.migrations]
is configured,
mops check
,
mops build
, and
mops check-stable
automatically inject
--enhanced-migration
. Do not add
--enhanced-migration
to
[canisters.<name>].args
— mops will error.
Create migration files directly in the
chain
directory.
After
mops check --fix
(or
mops check <canister>
) confirms the chain compiles, run
mops build
to produce the wasm artifact.
Use
mops build --check-deploy
, or set
[build].check-deploy = true
for every build, to install each built Wasm on a fresh PocketIC canister and catch module validation, initialization, and installation failures. Requires
[toolchain] pocket-ic
(a version from
9.0.0
up, or a local binary path) — or set
MOPS_POCKET_IC_URL
to an already-running PocketIC server (the pin is then ignored). Unpinned with no URL, the build errors naming
mops toolchain use pocket-ic 15.0.0
. Use
--no-check-deploy
to skip configured validation once. The command uses each canister's
initArg
, or
()
when omitted. Set
wasmMemoryLimit
to a positive integer byte limit on a canister to check deployment under that limit. PocketIC errors are reported as provided by the client, and installation failures are collected across canisters. Before installation, Mops runs
moc --stable-compatible
from a temporary empty-actor
.most
to each generated
.most
. If moc reports incompatibility, Mops emits
MOPS-CHECK-DEPLOY-SKIPPED
with the compiler diagnostic and does not check that canister on fresh PocketIC. Eligible siblings are still checked; validate the skipped upgrade against representative baseline state.
check-limit
(optional) caps how many recent chain files
mops check
and
mops lint
consider — useful when the chain grows long and re-checking every old migration slows feedback down.
mops build
is unaffected by
check-limit
; it compiles the full chain, and when
[canisters.<name>.check-stable].path
is set it also folds the deployed baseline via
--stable-baseline
, so an applied migration edited, deleted, or backdated since deploy fails the build with
M0268
— the backstop for when
check-limit
trims that migration out of the folded
mops check
. When the limit kicks in, mops stages the included files into
.migrations-<canister>/
next to the
chain
directory (auto-
.gitignore
d).
moc
diagnostics may then print paths there — the real file lives in the
chain
directory with the same name.
Override
check-limit
for a single run with
--no-check-limit
(
mops check
,
mops check-stable
,
mops lint
) — e.g.
mops check --fix --no-check-limit
to autofix older, normally-trimmed migrations. On
mops check
and
mops check-stable
,
--no-check-limit
also suppresses the pending-migration warning.
When
check-limit
is set,
mops check-stable
(and the stable check inside
mops check
) reports if more migrations are pending than the limit allows — as an error if compat failed (replacing the misleading
moc
message), otherwise a warning.
配置
[canisters.<name>.migrations]
后,
mops check
、
mops build
和
mops check-stable
会自动注入
--enhanced-migration
。不要在
[canisters.<name>].args
中添加
--enhanced-migration
——mops 会报错。
直接在
chain
目录中创建 migration 文件。
在
mops check --fix
(或
mops check <canister>
)确认 chain 可编译后,运行
mops build
生成 wasm 制品。
使用
mops build --check-deploy
,或为每次构建设置
[build].check-deploy = true
,以便将每个构建出的 Wasm 安装到全新的 PocketIC canister 上,并捕获模块验证、初始化和安装失败。需要
[toolchain] pocket-ic
(
9.0.0
或更高版本,或本地二进制路径)——也可将
MOPS_POCKET_IC_URL
设置为指向已运行的 PocketIC 服务器(此时会忽略固定版本)。若未固定版本且没有 URL,构建会报错并提示
mops toolchain use pocket-ic 15.0.0
。使用
--no-check-deploy
可单次跳过已配置的验证。该命令使用每个 canister 的
initArg
;未指定时使用
()
。在 canister 上设置
wasmMemoryLimit
为正整数字节限制,以检查该限制下的部署。PocketIC 错误按客户端提供的内容报告,跨 canister 收集安装失败。安装前,Mops 会针对每个生成的
.most
,从临时空 actor
.most
运行
moc --stable-compatible
。如果 moc 报告不兼容,Mops 会发出
MOPS-CHECK-DEPLOY-SKIPPED
,并附上编译器诊断信息,且不会在全新 PocketIC 上检查该 canister。其他符合条件的同级 canister 仍会被检查;请针对有代表性的基线状态验证被跳过的升级。
check-limit
(可选)限制
mops check
和
mops lint
考虑的近期 chain 文件数量——当 chain 变长、重新检查每个旧 migration 拖慢反馈速度时很有用。
mops build
不受
check-limit
影响;它会编译完整 chain,并且在设置
[canisters.<name>.check-stable].path
时,还会通过
--stable-baseline
合并已部署基线。因此,自部署以来被修改、删除或回填日期的已应用 migration 会导致构建失败并报
M0268
——这是
check-limit
从合并后的
mops check
中裁掉该 migration 时的兜底。达到限制后,mops 会把纳入检查的文件暂存到
chain
目录旁的
.migrations-<canister>/
中(自动加入
.gitignore
)。届时 moc 诊断信息中可能会显示这些路径——真实文件位于
chain
目录中,且名称相同。
可通过
--no-check-limit
为单次运行覆盖
check-limit
(适用于
mops check
、
mops check-stable
、
mops lint
)——例如执行
mops check --fix --no-check-limit
,以自动修复通常会被裁掉的旧 migration。在
mops check
和
mops check-stable
上,
--no-check-limit
还会抑制待处理 migration 警告。
设置
check-limit
后,如果待处理的 migration 数量超过限制允许的范围,
mops check-stable
(以及
mops check
内部的 stable 检查)会进行报告——如果兼容性检查失败则报为错误,以替代容易误导的 moc 消息,否则发出警告。

mops remove <package>

mops remove <package>

bash
mops remove core
Removes from whichever section declares the package;
--dev
limits it to
[dev-dependencies]
. A package declared in both sections is removed from both.
bash
mops remove core
从声明该软件包的区块中移除;
--dev
将操作限制在
[dev-dependencies]
。如果两个区块都声明了某个软件包,则会从两者中移除。

Dependency Management

依赖管理

bash
mops outdated             # list outdated deps (caret-bound); exit 1 if any, 2 if the check failed
mops outdated core        # check a single package
mops update               # rewrite mops.toml versions within caret bound (no major-version crossing)
mops update core          # update specific package within caret bound
mops update --major       # allow updates that cross major versions
mops update --patch       # restrict to patch bumps only (mutually exclusive with --major)
mops update --verbose     # verbose output
mops sync                 # add missing / remove unused packages
mops sync --dry-run       # print what would change, write nothing
mops update
rewrites
mops.toml
in place (like
cargo upgrade
, not
cargo update
) and re-pins GitHub dependencies to their branch head. Like
mops outdated
, it exits
2
when it cannot run or complete — no
mops.toml
, a package that is not declared, or a dependency that failed to update (the other dependencies are still updated).
mops sync
needs a pinned
[toolchain] moc
— it reads imports with
moc --print-deps
. Packages imported only from
test
/
tests
/
bench
/
benchmark
directories are added to
[dev-dependencies]
; already-declared packages are never moved between sections.
bash
mops outdated             # list outdated deps (caret-bound); exit 1 if any, 2 if the check failed
mops outdated core        # check a single package
mops update               # rewrite mops.toml versions within caret bound (no major-version crossing)
mops update core          # update specific package within caret bound
mops update --major       # allow updates that cross major versions
mops update --patch       # restrict to patch bumps only (mutually exclusive with --major)
mops update --verbose     # verbose output
mops sync                 # add missing / remove unused packages
mops sync --dry-run       # print what would change, write nothing
mops update
会原地重写
mops.toml
(类似
cargo upgrade
,而不是
cargo update
),并把 GitHub 依赖重新锁定到其分支最新提交。与
mops outdated
一样,在无法运行或完成时以状态码 2 退出——没有
mops.toml
、声明了未定义的软件包,或某个依赖更新失败(其他依赖仍会更新)。
mops sync
需要已固定
[toolchain] moc
——它通过
moc --print-deps
读取 imports。仅从
test
/
tests
/
bench
/
benchmark
目录导入的软件包会添加到
[dev-dependencies]
;已声明的软件包绝不会在区块之间移动。

Other Commands

其他命令

mops self update

mops self update

Updates a global install (npm/pnpm
-g
) only, and fails if the
mops
on PATH did not end up on the new version. For
ic-mops
as a project dependency, run
npm i -D ic-mops@<version>
instead.
仅更新全局安装(npm/pnpm
-g
),如果 PATH 上的
mops
最终未切换到新版本,则会失败。如果将
ic-mops
作为项目依赖项,请改用
npm i -D ic-mops@<version>
。

mops publish

mops publish

bash
mops publish              # publish to the registry (runs tests/docs/bench by default)
mops publish --dry-run    # same local steps as publish; no registry contact / identity
mops publish --dry-run --no-test --no-docs --no-bench   # packaging checks only
mops publish --no-test --no-docs --no-bench
--dry-run
runs the same local publish pipeline (packaging checks, docs, changelog, tests, benchmarks) and prints the final file list, then stops before identity/upload.
--no-*
flags work as usual. It does not run canister config validation (SPDX/semver/name rules) or prove registry acceptance (already published, permissions, missing deps).
bash
mops publish              # publish to the registry (runs tests/docs/bench by default)
mops publish --dry-run    # same local steps as publish; no registry contact / identity
mops publish --dry-run --no-test --no-docs --no-bench   # packaging checks only
mops publish --no-test --no-docs --no-bench
--dry-run
运行与 publish 相同的本地发布流水线(打包检查、docs、changelog、tests、benchmarks),打印最终文件列表,然后在身份验证或上传前停止。
--no-*
标志照常工作。它不会运行 canister 配置验证(SPDX/semver/name 规则),也不会证明 registry 会接受该包(已发布、权限不足、缺少依赖等)。

mops test

mops test

Tests live in
test/*.test.mo
:
bash
mops test                         # run all tests
mops test my-test                 # filter by name
mops test --mode wasi             # use wasmtime (for to_candid/from_candid)
mops test --reporter files        # one line per file (default is verbose)
mops test --watch                 # re-run on file changes
mops test -- -Werror              # pass extra moc flags
Replica tests (actor files or
// @testmode replica
) run on PocketIC — the
pocket-ic
version from
[toolchain]
, or an already-running server when
MOPS_POCKET_IC_URL
is set (no pin needed; canister log output is not streamed in attached mode). Unpinned with no URL, they error naming
mops toolchain use pocket-ic 15.0.0
. Same for
mops bench
and
mops watch --test
. There is no
--replica
flag and no dfx replica.
测试位于
test/*.test.mo
:
bash
mops test                         # run all tests
mops test my-test                 # filter by name
mops test --mode wasi             # use wasmtime (for to_candid/from_candid)
mops test --reporter files        # one line per file (default is verbose)
mops test --watch                 # re-run on file changes
mops test -- -Werror              # pass extra moc flags
Replica 测试(actor 文件或
// @testmode replica
)在 PocketIC 上运行——使用
[toolchain]
中的
pocket-ic
版本,或在设置
MOPS_POCKET_IC_URL
时使用已运行的服务器(无需固定版本;在 attached 模式下不会流式传输 canister 日志输出)。未固定版本且没有 URL 时,会报错并提示
mops toolchain use pocket-ic 15.0.0
。
mops bench
和
mops watch --test
同理。不存在
--replica
标志,也不存在 dfx replica。

mops bench

mops bench

Benchmarks live in
bench/*.bench.mo
:
bash
mops bench                        # run all benchmarks
mops bench my-bench               # filter by name
mops bench --gc incremental       # select GC
mops bench --save                 # save results to .bench/<name>.json
mops bench --compare              # compare with saved results
mops bench -- -Werror             # pass extra moc flags
Benchmark 位于
bench/*.bench.mo
:
bash
mops bench                        # run all benchmarks
mops bench my-bench               # filter by name
mops bench --gc incremental       # select GC
mops bench --save                 # save results to .bench/<name>.json
mops bench --compare              # compare with saved results
mops bench -- -Werror             # pass extra moc flags

mops lint

mops lint

Runs lintoko (also runs automatically as part of
mops check
when lintoko is in toolchain):
bash
mops lint                 # lint all .mo files
mops lint --fix           # autofix lint issues
mops lint <name>          # filter to .mo files matching <name>
When
[canisters.<name>.migrations].check-limit
is set,
mops lint
skips the trimmed chain migrations to match what
moc
sees during
mops check
. To lint a trimmed migration on demand, pass an explicit filter (e.g.
mops lint OldMigrationName
) or
--no-check-limit
to lint the full chain.
运行 lintoko(当工具链中有 lintoko 时,也会作为
mops check
的一部分自动运行):
bash
mops lint                 # lint all .mo files
mops lint --fix           # autofix lint issues
mops lint <name>          # filter to .mo files matching <name>
设置
[canisters.<name>.migrations].check-limit
后,
mops lint
会跳过被裁掉的 chain migration,以匹配 moc 在
mops check
期间看到的范围。要按需 lint 被裁掉的 migration,请传入显式过滤器(例如
mops lint OldMigrationName
)或
--no-check-limit
以 lint 完整 chain。

mops format

mops format

bash
mops format               # format all .mo files
mops format --check       # check formatting without modifying
bash
mops format               # format all .mo files
mops format --check       # check formatting without modifying

mops watch

mops watch

bash
mops watch                # errors + warnings + format (the default set)
mops watch --warning      # errors + warnings only
mops watch -t             # errors + tests
Error checking is always on. Passing any flag selects only the named tasks, so add
-w
/
-f
when you want them alongside
-t
. Those four are the whole set — there is no
--generate
or
--deploy
.
bash
mops watch                # errors + warnings + format (the default set)
mops watch --warning      # errors + warnings only
mops watch -t             # errors + tests
错误检查始终开启。传入任何标志都只会选择指定的任务,因此当希望与
-t
同时运行时,请添加
-w
/
-f
。仅有这四种任务——不存在
--generate
或
--deploy
。

Common Patterns

常见模式

Warning suppression for a canister

抑制 canister 的警告

Use per-canister
args
(not global) for suppressions:
toml
[canisters.backend]
main = "src/backend/main.mo"
args = ["-A=M0198"]
使用每个 canister 的
args
(不要使用全局
args
)进行抑制:
toml
[canisters.backend]
main = "src/backend/main.mo"
args = ["-A=M0198"]

New project

新项目

bash
mops init -y
mops toolchain use moc latest        # pin latest moc (non-interactive)
mops toolchain use lintoko latest    # pin latest lintoko
mops add core
Then configure
[moc].args
,
[canisters]
, and
[build]
in
mops.toml
.
To update tools later:
mops toolchain update moc
or
mops toolchain update
(all tools).
bash
mops init -y
mops toolchain use moc latest        # pin latest moc (non-interactive)
mops toolchain use lintoko latest    # pin latest lintoko
mops add core
然后在
mops.toml
中配置
[moc].args
、
[canisters]
和
[build]
。
以后更新工具:
mops toolchain update moc
或
mops toolchain update
(更新所有工具)。