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 的 Tab 鍵自動完成指令碼。

shell
magiclock completion bash > /etc/bash_completion.d/magiclock
magiclock completion zsh  > "${fpath[1]}/_magiclock"
上一頁帳號與啟用下一頁Python API 參考