Astrale CLI 是做什麼的？
astrale 連接到既有的 Astrale 核心。它選取一個實例和身分，執行圖形讀取與修改，呼叫可呼叫的函式，安裝正在執行的網域，讀取核心日誌，並開啟經過驗證的檢視。
已渲染的指令說明對於旗標和預設值具有權威性：
astrale --help
astrale <command> --help
- 二進位檔：
astrale - 套件：
@astrale-os/cli - 執行環境：Node 22 或更新版本；原始碼開發預設使用 Node 26，同時也支援 Node 24 和 Bun
- 開發入口點：
bun cli/bin/astrale.ts <command>
指令表面
主要指令：
astrale status
astrale whoami
astrale use <name>
astrale get <target>
astrale query [sources...]
astrale introspect <origin-or-path>
astrale mutate
astrale call <path> [key=value...]
astrale token
astrale logs
astrale view [target-or-view]
astrale ui ...
astrale instance ...
astrale domain ...
astrale identity ...
astrale auth ...
astrale idp ...
astrale admin ...
與核心互動的指令共用 --format、--json、--raw、--url、-i/--instance、--timeout、--as、--creds、--anonymous 和 --debug（在適用情況下）。CLI 創建一個公開的核心 Call，其 Client Session 擁有遠端路由、新鮮憑證及一次安全的路由重試機制。
astrale ui 是本地專案工具，不接受任何核心、實例、身分或憑證選項，但 astrale ui request 除外，它是一個經過驗證的核心指令，並接受共用的核心選項。
使用 --anonymous 可在即使存在本機或書籤預設身分時省略呼叫者憑證。它不能與 --as 或 --creds 搭配使用；必要的可呼叫函式會拒絕匿名請求。
UI 專案
Astrale UI 是一個可樹搖（tree-shakeable）的執行時期套件，加上消費者擁有的模式、區塊和主題原始碼。使用精確的已發布 UI 版本初始化一個 React 和 Tailwind CSS v4 專案：
astrale ui init --preset astrale
astrale ui search "具有匯出功能的可編輯圖表"
astrale ui request "可存取的、具有建立功能的非同步組合框"
astrale ui add pattern/chart/line-basic
astrale ui add theme/observatory
astrale ui add ./my-playground-export.css
astrale ui doctor
astrale ui doctor --project ./apps/web
astrale ui preset apply compact
初始化會寫入 Base UI + Nova shadcn 配置、主題和預設 CSS 匯入，以及 astrale-ui.lock.json。鎖定檔記錄了精確的套件版本、Git 標籤、已解析的提交 SHA、shadcn 版本、Base UI 版本、預設值以及已安裝原始碼的雜湊值。註冊表元資料、包含的清單和項目檔案總是從該單一提交快照中讀取。
執行 astrale ui add 而不帶任何項目參數會啟動互動式選擇器。在 CI 中，請明確提供標準位址。一般 add 操作會拒絕本地編輯過的已安裝檔案；請審查這些檔案，然後僅在確定要取代時才使用 --overwrite --yes。--dry-run 不會更改專案檔案和鎖定檔。使用 astrale ui search <free-text> --json 來接收一個簡短的、排名後的候選清單，其中包含確切的示範程式碼及其 command 或執行時期 packageImport。
當搜尋無法滿足需求時，請使用 astrale ui request <free-text>。它會在選取的實例上呼叫 /:ui.astrale.ai:function.request，並帶有一個有邊界的意圖（1-512 個字元），並列印傳回的收據：{ state: "submitted", requestId, collaborationUrl } 或 { state: "pending" | "outcome-unknown" | "failed" | "conflict", requestId }。
安裝後，模式、區塊和主題即為應用程式擁有的原始碼。主題會被複製到 components/astrale/theme/，並透過在配置的主樣式表中進行一次相對匯入來啟用；本地 playground 匯出不需要註冊表擷取或 shadcn 呼叫。組合根目錄 className、行內 style、受控的 values/actions 以及穩定的 data-slot 結構仍對主機開放。套件擁有可重複使用的執行時期行為；CLI 或 SDK 都未嵌入 UI 套件或 Base UI。
路徑
使用標準的核心路徑：
| 形式 | 範例 |
|---|---|
| 網域根目錄 | /:notes.example.dev |
| 類別 | /:notes.example.dev:class.Note |
| 靜態可呼叫函式 | /:notes.example.dev:class.Note:list |
| 實例可呼叫函式 | @node-id::notes.example.dev:class.Note.method.archive |
| 節點 ID | @node-id |
| 主動呼叫者簡寫 | @self |
靜態分發在方法前使用一個冒號。實例分發使用 ::，後接完整的網域限定方法鍵。使用 astrale introspect <origin> --bundle 探索方法。自省可以使用類別接收器來檢查實例合約；呼叫它需要一個已觀測到的實例路徑。當 @self 出現在呼叫路徑的開頭或作為純粹的 key=@self 值時，CLI 會在簽署前將其展開。它不會在 --data、stdin JSON、URL 或任意子字串內被改寫。
astrale get @self --json
astrale introspect /:notes.example:class.Note::notes.example:class.Note.method.archive
astrale call /:blog.example:class.Author:list limit=10
astrale call /:admin.astrale.ai:core.fleet::admin.astrale.ai:class.Fleet.method.listInstances
實例與網域
astrale instance 結合了管理佈建的實例和本地書籤：
astrale instance create my-app
astrale instance root import development --yes
astrale instance invite my-app [email protected]
astrale instance invitation status @invitation-id
astrale instance status my-app
astrale instance status staging --bookmarked
astrale instance list --include-retired --admin-only --json
astrale instance use my-app
astrale instance bookmark staging --url https://kernel.example.com
astrale instance forget staging
在腳本中使用明確的 -i <instance>。instance delete 影響的是管理受管的實例；instance forget 只移除本地書籤。instance status 預設回報 Admin 擁有的生命週期；加上 --bookmarked 則改為探查一個本地書籤的準確發行者、JWKS 和 TLS 信任。instance invite 需要管理該精確實例的權限，並且只授予實例成員存取權。它會立即回傳持久的邀請；Admin 會在 WorkOS 接受後自動具體化子 Shell 存取。instance invitation status <id> 對保留的邀請執行一次唯讀觀察。completed 表示存取已具體化；accepted、registering 和 registered 是中間狀態，並非已完成的存取。該指令需要精確的邀請 ID，且不會改變其狀態。instance invitation reconcile <id> 是診斷性復原，並非正常的邀請流程。
如果沒有部署 Admin 網域，astrale instance list 無法擷取受管實例（金鑰支援的身分沒有 Admin 令牌）。請使用 astrale instance list --bookmarked。
Fleet 管理員可以在一般 Admin 庫存中加上 --include-retired。預設會排除已退役的墓碑；包含的已退役實例使用相同的輸出格式，並由終端狀態 state: "deleted" 標識。可選的 issuer 僅在 Admin 保留了確切證據時存在。無法連線不代表已退役。當機器可讀封裝中應省略本地書籤時，請加上 --admin-only。
instance create 透過配置的 Admin 網域並以 WorkOS 呼叫者身分進行佈建；Admin 擁有主機放置權。instance create 和 instance root import 都不接受 --host。
instance root import <slug-or-id> 透過 Admin 透過端到端加密的一次性傳輸，擷取目標擁有實例的根簽署身分。它會將該身分在本地匯入為 <slug>-root，而不是 Admin 或主機的根身分。使用 --admin <bookmark> 或 --admin-url <url> 來選擇另一個 Admin 端點。復原需要重新邀請。