CLI 概览

Almirant CLI (almirant) 是一款面向两类用户的统一工具：

两种流程共用同一个二进制文件和同一份配置文件。区别仅在于你使用的命令集。

可以做什么

任务	命令	指南
向 Almirant 后端进行身份验证	`almirant login`	连接仓库
将当前目录连接到项目	`almirant init` / `almirant link`	连接仓库
安装 self-hosted 实例	`almirant install`	Self-hosted 安装
查看本地 stack 状态	`almirant ps`	运维 stack
读取本地 stack 日志	`almirant logs`	运维 stack
停止本地 stack	`almirant down`	运维 stack
升级 stack	`almirant upgrade`	运维 stack
管理账户（SaaS、self-hosted）	`almirant accounts` / `almirant use`	多个账户

CLI 以 npm 包形式发布（用 Go 编写的独立可执行文件）：

bun add -g almirant@latest
# o
npm i -g almirant

验证安装：

almirant version

提示

如果你只想将仓库连接到 SaaS 项目，最短的指南是连接仓库。你不需要其他内容。

要理解任意命令的输出，请记住以下三个概念：

CLI 保存一个或多个账户。每个账户是一组信息：

apiBaseUrl：后端所在位置（例如 SaaS 的 https://api.almirant.ai，或 self-hosted 的 https://miempresa.com/api）。
appBaseUrl：前端所在位置。
id：账户的稳定标识符，供生成的配置使用。
label：供人使用的本地别名（local-m1pro、prod-saas、kroko-dev）。
apiKey：CLI 用于向后端进行身份验证的令牌。

init、link 或 config 等命令针对一个活动账户运行。你可以通过 almirant use <label> 或 almirant use 的交互式选择器在多个账户之间切换。

若在自己的服务器上安装 Almirant，CLI 会将源代码克隆到 ~/.almirant/stack/，并使用 Docker Compose 启动容器。所有 ps、logs、down 和 upgrade 命令默认使用该目录（可通过 --dir 修改）。

本地 stack 与账户互相独立：你可以运行 self-hosted stack，同时配置指向 SaaS 的账户，不会发生冲突。

当你在仓库根目录执行 almirant init 或 almirant link 时，CLI 会在该仓库中写入两项内容：

.mcp.json：无密钥 MCP 配置。不包含令牌：它会执行 almirant mcp proxy，后者从 ~/.almirant/config.json 读取账户，并在内存中附加 bearer token。
.agents/ 和 .claude/skills/：使智能体知道如何与 Almirant 交互的 skill 模板。

这些内容均不会修改 Almirant 数据库：它们只是仓库的本地元数据。