命令行

本頁說明如何呼叫 lip：有哪些命令、參數怎樣讀取、輸出寫到哪裡、結束狀態代表什麼，以及試執行和 Ctrl+C 的行為。每個命令有自己的頁面；這裡寫的是它們共有的規則。

概要

text

lip
lip (-h | --help)
lip (-v | --version)
lip (cache | config | daemon | pkg) (-h | --help)
lip <command> [<argument>...]

概要中，word 照原樣書寫，<name> 要取代成具體的值，[x] 可以省略，x | y 表示二選一，(x | y) 把備選項括在一起，x... 表示 x 出現一次或多次。

呼叫方式	lip 的行為
`lip`	標準輸入和標準輸出都是終端機時，執行介面；否則把 `lip` 的幫助寫到標準輸出。
`lip -h`、`lip --help`	把 `lip` 的幫助寫到標準輸出，後面跟什麼都一樣。
`lip -v`、`lip --version`	把自己的版本（一個 SemVer 版本）和一個換行寫到標準輸出，後面跟什麼都一樣。
`lip cache -h`、`lip config -h`、`lip daemon -h`、`lip pkg -h`	把該命令組的幫助寫到標準輸出。`--help` 相同。
`lip --daemon`	作為常駐程式執行直到結束，不輸出任何內容。lip 自己會這樣啟動它，你不需要手動執行。
`lip <command> ...`	執行該命令。

輸出幫助或版本時結束代碼為 0。第一個參數以 - 開頭而又不是上面這些時，屬於用法錯誤。

命令

用於執行伺服器的命令：

命令	作用
`lip setup`	選擇工作區的遊戲和載入器。
`lip install`	向工作區安裝套件。
`lip uninstall`	從工作區解除安裝套件。
`lip update`	更新已安裝的套件。
`lip list`	列出已安裝的套件。
`lip run`	執行工作區的伺服器。
`lip cache clean`	刪除快取。
`lip config get`、`set`、`list`、`delete`	讀寫設定。

用於常駐程式的命令：

命令	作用
`lip daemon status`	顯示常駐程式是否在執行。
`lip daemon stop`	停止常駐程式。

用於開發套件的命令：

命令	作用
`lip pkg init`	為新套件建立 `lip.toml`。
`lip pkg pack`	把一個目錄封裝成 ZIP 歸檔。
`lip pkg view`	以 JSON 顯示套件的套件檔和版本。
`lip pkg migrate`	把目前目錄中的 `tooth.json` 移轉為 `lip.toml`。

用於 lip 自身的命令：

命令	作用
`lip self-update`	把 lip 更新到最新發佈的版本。

cache、config、daemon 和 pkg 是命令組：由兩個詞組成的命令名的第一個詞。

參數

命令名、命令組名和選項名都區分大小寫。

第一個參數是單個詞的命令名，或者一個命令組。命令組後面必須是 -h、--help，或者該組某個命令的第二個詞。其他寫法都是用法錯誤，命令組後面什麼都不跟也是。
-- 在 lip 中不是分隔符：任何一個參數是 -- 都是用法錯誤。
選項和操作數可以按任意順序寫在命令名之後。操作數按給出的順序賦值。

命令的參數中，以 - 開頭的都是選項：

形式	含義
`--<name>`	長選項 `<name>`。
`-<c>`	短選項 `<c>`，一個字元。
`--<name>=<value>`	長選項 `<name>`，值為 `<value>`。
`-<c>=<value>`	短選項 `<c>`，值為 `<value>`。

需要值的選項如果沒有用 = 書寫，就把下一個參數當作它的值。這個參數不能以 - 開頭。
值不能為空。
開關是不帶值的選項。同一個開關寫多次，效果和寫一次相同。
需要值的選項寫多次時，以最後一次的值為準。
短選項不能合併：-nh 的含義沒有定義。給開關帶上值（如 --json=true）的含義也沒有定義。不要這樣寫。

其餘的參數都是操作數。

用法錯誤

命令的參數在下列情況下屬於用法錯誤：

某個選項不是該命令的選項；
需要值的選項沒有值；
概要中要求的操作數或選項缺失；或者
操作數比命令接受的多。

遇到用法錯誤時，lip 向標準錯誤寫一條消息，以非零結束代碼結束，不做其他任何事，也不寫失敗報告。

所有命令共有的選項

選項	說明
`-h`、`--help`	把該命令的幫助寫到標準輸出，並以結束代碼 0 結束。命令不做其他任何事。

-h 優先於缺失的操作數和未知的選項：lip install -h 和 lip install -h --bogus 都輸出幫助。它不優先於缺失的選項值和過多的操作數，這兩種情況仍然是用法錯誤。

工作目錄

每個命令的工作區就是目前工作目錄。參數中的相對路徑相對於它。沒有用來指定其他工作區的選項：請先切換目錄。

輸出

結果是命令被要求給出的資料，寫到標準輸出。只有 list、pkg view、config get、config list、daemon status 和 self-update --check 有結果。
消息是其餘的一切：進度、資訊、警告、錯誤、最後的成功提示。消息寫到標準錯誤。它的措辭可能隨版本變化，不要解析它。
幫助寫到標準輸出。

因此 lip list > packages.txt 只儲存清單，2> /dev/null 只隱藏消息。消息始終是英文。

JSON

下列命令接受 --json。此時標準輸出只收到 JSON 形式的結果，後跟一個換行：

命令	JSON 結果
`lip list --json`	`{ "ExplicitInstalled": [...], "ImplicitInstalled": [...] }`
`lip config get <KEY> --json`	值，作為 JSON 字串；或 `null`。
`lip config list --json`	一個物件，把每個鍵映射到它的值或 `null`。
`lip daemon status --json`	`{ "running": false }`，或 `{ "running": true, "version": "...", "pid": ... }`。

lip pkg view 始終輸出 JSON，沒有 --json 選項。不帶 --json 時，結果的排版是給人看的，可能會變化。

結束狀態

結束代碼	含義
`0`	命令成功。
非 `0`	命令失敗，包括用法錯誤。標準錯誤上的消息說明原因。

lip run 是例外：一旦啟動了伺服器，它就以伺服器的結束代碼結束。

因用法錯誤以外的原因失敗的命令可能會寫一份失敗報告，即工作區中 .lip/logs/ 下的一個檔案，並在消息中給出它的路徑。參見失敗報告。

套件參數

install、update 和 pkg view 接受套件參數。lip 按下面第一條適用的規則對每個套件參數分類：

URL。 以 https:// 開頭的參數是一個 ZIP 歸檔的 URL。其他後跟 :// 的協議（如 http://、file://）無效。
本機路徑。 取參數中最後一個 # 之前的部分；如果整個參數就是一個存在的檔案或目錄，則取整個參數。滿足下列任一條件時，它是本機路徑：
- 這部分以 ./、../、.\ 或 ..\ 開頭；
- 這部分是 . 或 ..；
- 這部分是絕對路徑；或者
- 這部分以 .zip 結尾（不區分大小寫）或是一個存在的檔案或目錄，並且參數中不含 @。
不存在的本機路徑無效。
遠程儲存庫。 其餘的參數：<repo>[#<variant>][@<ref>]。不含 / 的 <repo> 是 LiteLDev 的儲存庫：LeviLamina@1.9.7 就是 github.com/LiteLDev/LeviLamina@1.9.7。

URL 和本機路徑的末尾可以帶 #<variant>。遠程儲存庫的引用是下列之一：

引用	選取
無	儲存庫的版本標籤（`v<version>`），從高到低。
`@<version>`	標籤 `v<version>` 的提交。
`@branch:<name>`	該分支指向的提交。
`@tag:<name>`	該標籤指向的提交。
`@rev:<commit>`	該 id 的提交：完整的 40 位十六進制數字。

套件參數無效時，命令在做出任何變更之前失敗。lip install 中有每種形式的示例。

環境

lip 只為一種環境安裝套件：執行端 server、平臺 win-x64，無論 lip 執行在什麼系統上。如果工作區的狀態檔記錄了其他執行端，或者 win-x64 和 linux-x64 以外的平臺，setup、install、uninstall、update 和 run 都會失敗。記錄 linux-x64 的狀態檔會被當作 win-x64 的來讀取。

工作區操作

不帶 --dry-run 的 setup、install、uninstall 和 update 各執行一次工作區操作：對工作區的變更要麼全部完成，要麼完全不做。

操作會取得工作區鎖 .lip/lock。如果另一個處理程序持有它，命令立即失敗，不做任何變更。
如果之前有操作被中斷，下一次操作會先把它完成或復原。
在工作區開始變更之前失敗，不會留下任何變更。之後失敗，變更會被復原。已經執行過的鉤子命令不會被撤回。

lip 的工作方式有完整的說明。

試執行

setup、install、uninstall 和 update 接受 -n 或 --dry-run。試執行執行所有不會改變任何東西的步驟，並用消息說明操作會對哪些套件做什麼。試執行：

不取得工作區鎖，所以另一個命令正在變更工作區時也能執行；
不恢復被中斷的操作：存在 .lip/journal 時，它會說明這一點，並按工作區目前的樣子來規劃；
不執行任何鉤子命令；
不提問；並且
不建立、取代或刪除任何檔案和目錄，只有一個例外：失敗時可能寫一份失敗報告。

試執行仍然會使用網路來解析套件，但不向快取寫入任何內容。

Ctrl+C

Ctrl+C 的作用取決於 lip 正在做什麼：

lip 正在	第一次 Ctrl+C	第二次 Ctrl+C
規劃操作，工作區尚未變更	立即結束 lip。沒有任何變更。
變更工作區	取消操作並復原它的變更。	立即結束 lip。工作區的下一次操作會恢復它。
用 `lip run` 執行伺服器	向伺服器傳送 `stop`。伺服器結束後 lip 才結束。	沒有更多作用：lip 不會先於伺服器結束。
連線著託管伺服器（`lip run --managed`）	向伺服器傳送 `stop`。你保持連線，直到它結束。	相同。

其他信號參見 lip run。

常駐程式

除 daemon 組的命令以外，所有命令以及介面都由常駐程式執行：它是屬於你這個使用者的背景 lip 處理程序，由第一條命令啟動。你感覺不到區別：命令使用你的工作目錄、你的環境變數、你的終端機和你的 Ctrl+C，lip 以命令的結束代碼結束。

如果 lip 無法啟動或連線常駐程式，它會寫一條消息，然後自己執行命令。只有 lip run --managed 離不開常駐程式。參見 lip daemon。

另請參閱

介面參考：介面的每個頁面對應哪些命令。
設定和檔案。
用命令執行伺服器和管理套件。