跳到主要内容

命令参考

完整的 CLI 命令列表。随时可查看内联帮助：

almirant --help
almirant <comando> --help

almirant install​

在当前机器上安装 self-hosted Almirant 实例。它会将源仓库克隆到 --dir（默认 ~/.almirant/stack），并执行 scripts/install.sh，该脚本构建 Docker 镜像、生成含随机密钥的 .env.production，然后启动 stack。

almirant install [flags]
Flag默认值说明
--branchmain要安装的 git 分支或 tag
--dir~/.almirant/stack克隆 stack 的目录
--from-dir—使用已有本地 clone（air-gapped 安装，CLI 不会操作 git）
--non-interactivefalse跳过安装程序提示（使用默认值）
--public-url—提供 Almirant 服务的公开 URL（不带末尾斜杠）
--repoalmirant-ai/almirant要克隆的 GitHub 仓库
--with-discordfalse启用 Discord bridge profile
--with-proxyfalse启用反向代理（Caddy）profile

行为

  • 如果 --dir 已包含先前的 clone，CLI 会在 --branch 上执行 git fetch 加 fast-forward pull，而不会重新克隆。
  • 安装程序仅在首次生成 .env.production。如果文件已存在，会原样保留（你的密钥不变）。
  • --public-url 会同时写入 NEXT_PUBLIC_SITE_URL、BETTER_AUTH_URL、BETTER_AUTH_TRUSTED_ORIGINS 和 CORS_ORIGIN。稍后更改该 URL 需要重新构建前端（参阅运维 stack）。

示例

# Instalacion interactiva, te pregunta la URL publica
almirant install

# Instalacion sin prompts, con URL fijada
almirant install --non-interactive --public-url https://almirant.example.com

# Instalacion desde un tag concreto
almirant install --branch v1.2.3

# Instalacion air-gapped desde un clone existente
almirant install --from-dir /opt/almirant-release --non-interactive
备注

安装程序必须在目标机器上运行。install 没有通过 SSH 远程运行的模式；若要对已安装的 stack 执行此操作，请使用 almirant upgrade --host <ssh>。

almirant login​

打开浏览器，针对 Almirant 后端完成 OAuth 流程，获取生成的 API key，并将账户保存到 ~/.almirant/config.json。

almirant login [flags]
Flag默认值说明
--api-urlpromptAPI 基础 URL（覆盖 ALMIRANT_API_URL 和提示）
--app-url从 --api-url 推导前端基础 URL
--nameAlmirant CLIAPI key 保存到后端时使用的标签

每次登录都会创建或更新一个具有稳定 ID 和人类可读标签的本地账户。你可针对 SaaS、staging 和多个 self-hosted 实例重复执行。

almirant login
almirant login --api-url https://almirant.miempresa.com/api
almirant accounts list
提示

API keys 保存在权限为 600 的 ~/.almirant/config.json。init 和 link 生成的项目文件不包含 bearer token。

almirant init​

仓库中的完整首次使用流程。它检测项目类型，允许选择或创建账户，选择或创建项目，并写入：

  • .mcp.json：执行 almirant mcp proxy 的无密钥 MCP 配置。
  • .claude/skills/ 和 .agents/skills/：skill 模板。
almirant init [flags]
Flag默认值说明
--api-url—API URL（仅添加新账户时）
--app-url—前端 URL（仅添加新账户时）
--nameAlmirant CLIAPI key 标签（仅新账户）

行为

  • 如果已有已保存账户，init 会让你选择一个。
  • 如果没有账户，会触发与 almirant login 相同的 OAuth 流程。
  • 如果 .mcp.json 已存在，会合并 almirant 条目而不影响其他 MCP 服务器。
  • 生成的条目使用 type: "stdio"、command: "almirant" 和 args: ["mcp", "proxy", ...]。

与 init 相同，但不包含 OAuth 流程。要求你已通过 almirant login 验证过至少一个账户。

almirant link

除 --help 外不接受 flags。它从已保存账户中选择账户和项目，并在当前目录写入 .mcp.json 加 skills。

何时使用各命令
  • init：新团队中的首次使用，或希望 CLI 逐步引导并包含登录。
  • link：已完成身份验证，只想把另一个仓库连接到现有项目。

almirant accounts​

通过主快捷方式管理账户。出于兼容性考虑，相同子命令也存在于 almirant config accounts ... 下。

almirant accounts list
almirant accounts rename <ref> <label>
almirant accounts add
almirant accounts remove <ref>
almirant accounts set-default <ref>
子命令说明
list列出标记、索引、标签、电子邮件、API URL 和 API key 状态
addalmirant login 的别名
rename <ref> <label>更改账户的人类可读标签
remove <ref>删除本地账户（--yes 跳过确认）
set-default <ref>设置默认活动账户

<ref> 可以是标签、稳定 ID、唯一电子邮件或从 1 开始的索引。

almirant use [label|id|email|index]​

选择活动账户。不带参数时打开交互式选择器。

almirant use local-m1pro
almirant current

almirant current 会输出标签、ID、电子邮件、API URL 和 key 前缀，不会暴露完整令牌。

almirant mcp proxy​

运行 MCP 智能体使用的 stdio 代理。

almirant mcp proxy --project-id <id> [--account <label|id|email|index>]

代理从 ~/.almirant/config.json 读取账户，将流量转发到 <apiBaseUrl>/mcp?projectId=<id>，仅在内存中附加 bearer token。不要把令牌写入 .mcp.json、.codex/config.toml 或 shell 文件。

almirant ps​

针对生产 compose 文件的 docker compose ps 包装器。

almirant ps [flags]
Flag默认值说明
--dir~/.almirant/stackstack 目录

almirant logs​

生产 stack 的 docker compose logs 包装器。

almirant logs [service...] [flags]

位置参数是用于限制输出的服务名称（例如 backend、frontend、db-init）。

Flag默认值说明
--dir~/.almirant/stackstack 目录
-f, --followfalse实时跟随输出（tail -f）
--tail0（全部）每个服务仅显示最后 N 行

示例

# Todos los servicios, las ultimas 100 lineas
almirant logs --tail 100

# Solo backend y frontend, en tiempo real
almirant logs -f backend frontend

almirant down​

针对生产 stack 执行 docker compose down。默认保留数据卷。

almirant down [flags]
Flag默认值说明
--dir~/.almirant/stackstack 目录
--rmi—同时删除镜像。值为 local 或 all
--volumesfalse破坏性操作：同时删除卷（会丢失全部数据）
注意

--volumes 不可逆。仅在希望从零开始时使用。对于安装失败后的干净测试，通常应执行：almirant down --volumes。

almirant upgrade​

将 stack 升级到指定 branch 的最新版本。

本地模式（不带 --host）：在 --dir 中执行 git fetch 加 pull，重建镜像并重启容器。

远程模式（带 --host）：通过 SSH 针对机器执行 scripts/update-remote.sh。

almirant upgrade [service...] [flags]

位置参数是限制重建范围的服务名称（例如 frontend backend）。省略时重建全部服务。

Flag默认值说明
--branchmain要获取的 branch
--dir~/.almirant/stackstack 目录（本地模式）
--host—远程升级使用的 SSH host
--local-repo—本地 clone 路径，以避免下载脚本（远程模式）
--repoalmirant-ai/almirant升级脚本的仓库（远程模式）

示例

# Upgrade completo del stack local
almirant upgrade

# Solo reconstruir el frontend (mas rapido si solo cambiaste UI)
almirant upgrade frontend

# Upgrade de un servidor remoto via SSH
almirant upgrade --host [email protected]

almirant config​

管理保存在 ~/.almirant/config.json 的 CLI 配置。日常使用时，优先采用 almirant accounts、almirant use 和 almirant current 快捷方式；config 保留完整命令树和高级子命令。

almirant config [comando]

almirant config show​

输出所有已配置账户，不泄露密钥。API key 仅以其前缀显示（例如 alm_k1_…）；永不输出完整 key。

almirant config accounts​

账户管理器的完整别名，同样可作为 almirant accounts ... 使用。

子命令说明
list列出所有已配置账户
addalmirant login 的别名，用于添加新账户
rename <ref> <label>重命名账户的人类可读标签
remove <ref>从本地配置中删除账户
set-default <ref>设置默认活动账户

almirant config set​

子命令说明
api-url <url> [--account <ref>]更改账户的 API URL（后端迁移时很有用）

almirant config rotate​

子命令说明
api-key [--account <ref>]为所选账户生成新 API key 并替换旧 key。服务器上的旧 key 会失效。

almirant config reset​

删除全部账户，并留下空配置。

almirant config reset       # te pide confirmacion
almirant config reset -y    # sin prompt, para scripts

almirant version​

输出 CLI 版本和构建元数据。

almirant version

适用于报告 issue，以及决定是否值得通过 bun add -g almirant@latest 更新。

环境变量​

若干命令支持与其 flags 等效的环境变量。以下列出它们，因为它们在 CI 和脚本中很有用。

变量受影响的命令等效 flag
ALMIRANT_API_URLlogin, init--api-url
ALMIRANT_APP_URLlogin, init--app-url
ALMIRANT_NONINTERACTIVEinstall (via scripts/install.sh)--non-interactive
ALMIRANT_PUBLIC_URLinstall (via scripts/install.sh)--public-url
ALMIRANT_WITH_PROXYinstall--with-proxy
ALMIRANT_WITH_DISCORDinstall--with-discord