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，其客户端会话拥有远程路由、新鲜凭证以及一次安全的过期路由重试。
astrale ui 是本地项目工具，不需要内核、实例、身份或凭据选项，但 astrale ui request 例外，它是一个经过身份验证的内核命令，并接受共享的内核选项。
使用 --anonymous 可以在存在本地或书签默认身份时省略调用者凭据。它不能与 --as 或 --creds 同时使用；必需的可调用对象会拒绝匿名请求。
UI 项目
Astrale UI 是一个可摇树优化的运行时包，外加消费者拥有的模式、块和主题源码。使用确切的已发布 UI 版本初始化一个 React 和 Tailwind CSS v4 项目：
astrale ui init --preset astrale
astrale ui search "editable chart with export"
astrale ui request "accessible async combobox with creation"
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 中，请显式提供规范地址。普通添加拒绝本地编辑过的已安装文件；请审查这些文件，然后仅在有意替换时使用 --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、受控的值/操作以及稳定的 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 默认报告管理员拥有的生命周期；添加 --bookmarked 可探查一个本地书签的确切签发者、JWKS 和 TLS 信任。instance invite 需要管理确切实例的权限，并仅授予实例成员访问权限。它立即返回持久的邀请；管理员在 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 管理员可以添加 --include-retired 到普通的 Admin 库存中。默认排除已退役的墓碑；包含的已退役实例使用相同的输出形状，并通过终端 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 端点。