CLI 速查

magiclock 的每一个子命令和参数，都在这一页。

一切都是同一个命令：magiclock <子命令> [选项]。magiclock --version 打印已安装版本；直接执行 magiclock 打印帮助。

activate

认证并把这台机器纳入账号——幂等，可以放心重复执行。

参数含义
--server URL授权服务器地址（依次回退到已保存的会话、$MAGICLOCK_SERVER）。
--token TOKENBearer 令牌（依次回退到已保存的会话、$MAGICLOCK_TOKEN）。
--with-token无人值守模式：从 $MAGICLOCK_TOKEN 或标准输入读取一个门户铸造的令牌。
--no-browser需要登录时打印链接 + 验证码，而不是打开浏览器。

status

查看这台机器的账号与激活状态。

参数含义
--offline跳过与服务器的实时往返，只根据本地状态汇报。

protect

把一个 .py 文件（或一整个目录，递归处理）加密成带闸门的 .pya。

shell
magiclock protect PATH [-o OUT] [--remove]
                  [--trial | --expires-in DURATION | --expires-at DATE]
                  [--bind-machine [--passphrase] | --passphrase | --emit-key]
参数含义
PATH要保护的 .py 文件，或要递归保护的目录（.venv、venv、__pycache__、.git、dist、build 会被自动跳过）。
-o, --out输出路径（目录模式下是输出根目录）。
--remove加密后删除明文 .py 文件。
--trial固定 48 小时自毁——用于演示。
--expires-in DURATION一段时长后停止解密（如 30d）。
--expires-at DATE到指定日期后停止解密（如 2026-12-31）。
（不加任何绑定参数）默认：免密钥便携——任何装了 magiclock 的机器都能解密；没有锁，也没有密钥。
--bind-machine机器锁定产物：只能在这台已激活的机器上解密。再加 --passphrase 即为二因子锁（机器加上口令）。
--passphrase用口令解锁（读取 $MAGICLOCK_PASSPHRASE，否则交互式提示）——单独用是便携档，配合 --bind-machine 是第二因子。
--emit-key便携产物，用生成好的密钥解锁，密钥打印出来供带外分发。

--trial/--expires-in/--expires-at 彼此互斥；--passphrase 与 --emit-key 互斥；--emit-key 不能与 --bind-machine 同时使用。

protect-model

把一个模型或任意资源加密成 .enc 信封。有效期与绑定相关参数与 protect 相同（默认免密钥便携，--passphrase/--emit-key，--bind-machine（可加 --passphrase）），另外还有：

参数默认值含义
PATH—要加密的文件。
-o, --out<path>.enc输出路径。
--feature NAMEai_model解锁这个产物所需的授权能力。
--remove关闭加密后删除明文文件。

build

把应用编译成原生二进制，授权闸门自动插入每一个模块。完整流程见编译强档。

参数默认值含义
entry—入口 .py 文件。
-o, --output-dirdist构建输出目录。
--source-root入口文件所在目录要扫描/转换的项目根目录。
--module开启编译成单文件原生扩展。
--standalone—改为编译成自包含的应用目录，与 --module 互斥。
--no-compile关闭只做扫描 + 注入 + 内嵌，跳过原生编译。
--keep-tmp关闭保留中间转换目录。
--model PATH无加密并打包一个模型（可重复）。
--model-lock-passphrase关闭给打包的模型加二因子锁（需要至少一个 --model，且需要 --bind-machine）。
--model-trial / --model-expires-in / --model-expires-at无打包模型的有效期——彼此互斥。
--bind-machine关闭机器锁定构建：授权闸门编译进每一个模块；只能在这台机器的保险库下运行。不加它就是默认的便携构建——没有闸门、可在任何机器上运行、模型免密钥。
--passphrase / --emit-key关闭仅限便携构建：打包模型改用口令派生或随机生成的共享密钥，替代免密钥默认。

run

运行一个 .py 或 .pya，闸门检查随之进行。

参数默认值含义
entry—要运行的文件。
--app-version1.0.0应用版本，会与你授权设置的 max_app_version 做比对。
--passphrase关闭提示输入解密口令（或读取 $MAGICLOCK_PASSPHRASE）——用于便携或二因子产物。
--key KEY—便携产物的解密密钥（base64），或读取 $MAGICLOCK_DECRYPT_KEY。

deactivate

把这台机器从你的账号中移除。

参数含义
--local-only只清空本地凭据，不释放席位、不通知服务器吊销。
--server URL用于释放请求的服务器地址。
--token TOKEN用于释放请求的 Bearer 令牌。

skill

把一份 Claude Code skill 装进当前项目，让 AI coding agent（比如 Claude Code）知道怎么用 MagicLock 保护这个项目。

shell
magiclock skill [--dir DIR] [--force] [--print]
参数含义
--dir DIR要安装到的项目根目录（默认当前目录）。
--force覆盖已存在的 SKILL.md。
--print把 skill 内容打印到标准输出，而不是写文件。

会写入 .claude/skills/magiclock-protect/SKILL.md，教会 agent 判断该用哪一档保护、并正确调用 protect/build。

completion

打印 shell 自动补全脚本。

shell
magiclock completion bash > /etc/bash_completion.d/magiclock
magiclock completion zsh  > "${fpath[1]}/_magiclock"
上一页账号与激活下一页Python API 参考