profile-commands

配置文件命令参考

本文档涵盖了与 Hermes 配置文件 相关的所有命令。关于通用的 CLI 命令，请参阅 CLI 命令参考。

hermes profile

hermes profile <subcommand>

用于管理配置文件（profile）的顶层命令。运行 hermes profile 而不带子命令会显示帮助信息。

子命令	描述
list	列出所有配置文件。
use	设置活动（默认）配置文件。
create	创建新的配置文件。
delete	删除配置文件。
show	显示配置文件的详细信息。
alias	重新生成配置文件的 shell 别名。
rename	重命名配置文件。
export	将配置文件导出为 tar.gz 归档文件。
import	从 tar.gz 归档文件导入配置文件。
install	从 Git URL 或本地目录安装配置文件分发版。请参阅 Profile Distributions。
update	重新拉取分发版管理的配置文件并重新应用其捆绑包。
info	显示配置文件的分布元数据（来源 URL、提交、最后更新）。

hermes profile list

hermes profile list

列出所有配置文件。当前活动的配置文件标有 *。

示例：

$ hermes profile list
  default
* work
  dev
  personal

无选项。

hermes profile use

hermes profile use <name>

将 <name> 设置为活动配置文件。之后所有的 hermes 命令（不带 -p）将使用此配置文件。

参数	描述
<name>	要激活的配置文件名称。使用 default 返回基本配置文件。

示例：

hermes profile use work
hermes profile use default

hermes profile create

hermes profile create <name> [options]

创建新的配置文件。

参数 / 选项	描述
<name>	新配置文件的名称。必须是有效的目录名称（字母数字、连字符、下划线）。
--clone	从当前配置文件复制 config.yaml、.env 和 SOUL.md。
--clone-all	从当前配置文件复制所有内容（配置、记忆、技能、会话、状态）。
--clone-from <profile>	从指定的配置文件克隆，而非当前配置文件。与 --clone 或 --clone-all 配合使用。
--no-alias	跳过包装脚本的创建。
--description "<text>"	一句话或两句话描述此配置文件擅长什么。由看板编排器（kanban orchestrator）用于根据角色（而非仅配置文件名称）分配任务。可跳过后续通过 hermes profile describe 添加。保存在 <profile_dir>/profile.yaml 中。
--no-skills	创建空配置文件，不启用任何捆绑技能。在配置文件中写入 .no-skills 标记，以便后续 hermes update 运行不会重新植入捆绑集，且拒绝与 --clone / --clone-all 结合使用（否则会复制技能）。适用于狭窄的编排器配置文件或沙箱配置文件，这些配置文件不应继承完整的技能目录。

创建配置文件不会将该配置文件的目录设置为终端命令的默认项目/工作目录。如果希望配置文件在特定项目中启动，请在该配置文件的 config.yaml 中设置 terminal.cwd。

示例：

# 空白配置文件——需要完整设置
hermes profile create mybot
 
# 从当前配置文件仅克隆配置
hermes profile create work --clone
 
# 从当前配置文件克隆所有内容
hermes profile create backup --clone-all
 
# 从指定配置文件克隆配置
hermes profile create work2 --clone --clone-from work

hermes profile describe

hermes profile describe [<name>] [options]

读取或设置配置文件的描述。描述由看板编排器用于根据每个配置文件擅长的领域来分配任务，而非仅通过配置文件名称猜测。保存在 <profile_dir>/profile.yaml 中，因此重启后仍然存在，并与网关共享。

无标志时，打印当前描述（如果为空则显示 (no description set for '<name>')）。

参数 / 选项	描述
<name>	要描述的配置文件。除非使用 --all --auto，否则为必需。
--text "<text>"	将描述设置为此确切文本（用户编写）。覆盖任何现有描述。
--auto	通过辅助 LLM 自动生成一两句描述，基于配置文件已安装的技能、配置的模型和名称。在 config.yaml 的 auxiliary.profile_describer 下配置模型。自动生成的描述标记为 description_auto: true，因此仪表板可以标记它们以供审核。
--overwrite	与 --auto 配合使用，也替换用户编写的描述（默认：跳过已显式设置描述的配置文件）。
--all	与 --auto 配合使用，扫描每个缺少描述的配置文件。

示例：

# 读取当前描述
hermes profile describe researcher
 
# 显式设置
hermes profile describe researcher --text "Reads source code and writes findings."
 
# 让 LLM 生成一个
hermes profile describe researcher --auto
 
# 为每个缺少描述的配置文件填充描述
hermes profile describe --all --auto

hermes profile delete

hermes profile delete <name> [options]

删除配置文件并移除其 shell 别名。

参数 / 选项	描述
<name>	要删除的配置文件。
--yes、-y	跳过确认提示。

示例：

hermes profile delete mybot
hermes profile delete mybot --yes

:::warning 此操作会永久删除配置文件的整个目录，包括所有配置、记忆、会话和技能。无法删除当前活动的配置文件。 :::

hermes profile show

hermes profile show <name>

显示配置文件的详细信息，包括其主目录、配置的模型、网关状态、技能数量和配置文件状态。

此处显示的是配置文件的 Hermes 主目录，而非终端工作目录。终端命令从 terminal.cwd 启动（在本地后端且 cwd: "." 时从启动目录启动）。

参数	描述
<name>	要检查的配置文件。

示例：

$ hermes profile show work
Profile: work
Path:    ~/.hermes/profiles/work
Model:   anthropic/claude-sonnet-4 (anthropic)
Gateway: stopped
Skills:  12
.env:    exists
SOUL.md: exists
Alias:   ~/.local/bin/work

hermes profile alias

hermes profile alias <name> [options]

在 ~/.local/bin/<name> 重新生成 shell 别名脚本。当别名被意外删除或在移动 Hermes 安装后需要更新时使用。

参数 / 选项	描述
<name>	要创建/更新别名的配置文件。
--remove	移除包装脚本而非创建它。
--name <alias>	自定义别名名称（默认：配置文件名称）。

示例：

hermes profile alias work
# 创建/更新 ~/.local/bin/work
 
hermes profile alias work --name mywork
# 创建 ~/.local/bin/mywork
 
hermes profile alias work --remove
# 移除包装脚本

hermes profile rename

hermes profile rename <old-name> <new-name>

重命名配置文件。更新目录和 shell 别名。

参数	描述
<old-name>	当前配置文件名称。
<new-name>	新的配置文件名称。

示例：

hermes profile rename mybot assistant
# ~/.hermes/profiles/mybot → ~/.hermes/profiles/assistant
# ~/.local/bin/mybot → ~/.local/bin/assistant

hermes profile export

hermes profile export <name> [options]

将配置文件导出为压缩的 tar.gz 归档文件。

参数 / 选项	描述
<name>	要导出的配置文件。
-o、--output <path>	输出文件路径（默认：<name>.tar.gz）。

示例：

hermes profile export work
# 在当前目录创建 work.tar.gz
 
hermes profile export work -o ./work-2026-03-29.tar.gz

hermes profile import

hermes profile import <archive> [options]

从 tar.gz 归档文件导入配置文件。

参数 / 选项	描述
<archive>	要导入的 tar.gz 归档文件路径。
--name <name>	导入后配置文件的名称（默认：从归档文件推断）。

示例：

hermes profile import ./work-2026-03-29.tar.gz
# 从归档文件推断配置文件名称
 
hermes profile import ./work-2026-03-29.tar.gz --name work-restored

分发版命令

:::tip 刚接触分发版？ 请先阅读 Profile Distributions 用户指南——它涵盖了原因、时机和方法，并包含完整示例。以下部分是在你已明确需求时的简洁 CLI 参考。 :::

分发版将配置文件转变为一个可分享的、带版本号的制品，以 Git 仓库形式发布。接收者使用一条命令即可安装分发版，之后无需触及本地记忆、会话或凭据即可就地更新。

auth.json 和 .env 永远不会成为分发版的一部分——它们保留在安装用户的机器上。

接收者的用户数据（记忆、会话、认证信息以及他们对 .env 的编辑）在初始安装和后续更新中始终保持不变。

:::info hermes profile export / import 仍然是用于在你自己的机器上进行本地备份和恢复的正确命令。分发版（install / update / info）是一个独立的概念：通过 Git 发布配置文件，以便他人可以安装。 :::

hermes profile install

hermes profile install <source> [--name <name>] [--alias] [--force] [--yes]

从 Git URL 或本地目录安装配置文件分发版。

选项	描述
<source>	Git URL（github.com/user/repo、https://...、git@...、ssh://、git://）或在其根目录包含 distribution.yaml 的本地目录。
--name NAME	覆盖清单中的配置文件名称。
--alias	同时创建 shell 包装器（例如 telemetry → hermes -p telemetry）。
--force	覆盖同名的现有配置文件。用户数据仍会被保留。
-y、--yes	跳过清单预览确认提示。

安装程序会显示清单、列出所需的环境变量，并在请求确认之前警告 cron 任务。所需的环境变量会写入 .env.EXAMPLE 文件，你复制为 .env 后填写。

示例：

# 从 GitHub 仓库安装（简写形式）
hermes profile install github.com/kyle/telemetry-distribution --alias
 
# 从完整 HTTPS Git URL 安装
hermes profile install https://github.com/kyle/telemetry-distribution.git
 
# 从 SSH 安装
hermes profile install git@github.com:kyle/telemetry-distribution.git
 
# 在开发过程中从本地目录安装
hermes profile install ./telemetry/

hermes profile update

hermes profile update <name> [--force-config] [--yes]

从其记录的源重新克隆分发版并应用更新。分发版拥有的文件（SOUL.md、skills/、cron/、mcp.json）会被覆盖；用户数据（记忆、会话、认证信息、.env）永远不会被触及。

config.yaml 默认被保留以保持你的本地覆盖设置。传递 --force-config 以重置为分发版提供的配置。

hermes profile info

hermes profile info <name>

打印配置文件的分布清单——名称、版本、所需 Hermes 版本、作者、环境变量要求、来源 URL/路径，以及最后 install 或 update 时记录的 Installed: 时间戳。用于在安装前检查共享配置文件需要什么，以及发现”这个配置文件是 6 个月前安装的，还没有更新过”的情况。

hermes profile list 还在 Distribution 列中显示分发版名称和版本；hermes profile show <name> / delete <name> 会显示来源 URL，让你一目了然地知道哪些配置文件来自 Git 仓库，哪些是本地创建的。

私有分发版

私有 Git 仓库无需额外配置即可作为分发版源——安装时会调用你正常的 git 二进制文件，因此你的 shell 已配置的任何认证方式（SSH 密钥、git credential 助手、GitHub CLI 存储的 HTTPS 凭据）都会透明地生效。

# 使用你的 SSH 密钥，与任何其他 `git clone` 相同
hermes profile install git@github.com:your-org/internal-assistant.git
 
# 使用你的 git credential 助手
hermes profile install https://github.com/your-org/internal-assistant.git

如果安装过程中克隆操作在终端中交互式地提示输入凭据，该提示会直接显示。请先按照正常使用 git clone 的方式对该仓库进行认证设置，然后再安装。

分发版清单（distribution.yaml）

每个分发版在其仓库根目录都有一个 distribution.yaml：

name: telemetry
version: 0.1.0
description: "Compliance monitoring harness"
hermes_requires: ">=0.12.0"
author: "Your Name"
license: "MIT"
env_requires:
  - name: OPENAI_API_KEY
    description: "OpenAI API key"
    required: true
  - name: GRAPHITI_MCP_URL
    description: "Memory graph URL"
    required: false
    default: "http://127.0.0.1:8000/sse"
distribution_owned:   # 可选；默认为 SOUL.md、config.yaml、
                      #   mcp.json、skills/、cron/、distribution.yaml
  - SOUL.md
  - skills/compliance/
  - cron/

hermes_requires 支持 >=、<=、==、!=、>、< 或裸版本号（视为 >=）。如果当前 Hermes 版本不满足要求，安装会以清晰的错误信息失败。

distribution_owned 是可选的。如果设置了，只有这些路径会在更新时被替换；配置文件中的其他内容保持为用户所有。如果省略，则应用上述默认值。

发布分发版

编写分发版只需一个 Git push 操作：

1. 在配置文件的目录中，创建至少包含 name 和 version 的 distribution.yaml。
2. 初始化 Git 仓库（或使用现有仓库）并推送到 GitHub/GitLab/Hermes 能够克隆的任何托管平台。
3. 告诉接收者运行 hermes profile install <你的仓库 URL>。

使用 Git 标签进行版本化发布——克隆 HEAD 的接收者会获得你的最新状态，你随时可以在清单中更新 version: 字段。

hermes -p / hermes --profile

hermes -p <name> <command> [options]
hermes --profile <name> <command> [options]

全局标志，用于在指定配置文件下运行任何 Hermes 命令，而不更改粘性默认配置文件。这会在此命令执行期间覆盖活动配置文件。

选项	描述
-p <name>、--profile <name>	用于此命令的配置文件。

示例：

hermes -p work chat -q "Check the server status"
hermes --profile dev gateway start
hermes -p personal skills list
hermes -p work config edit

hermes completion

hermes completion <shell>

生成 shell 补全脚本。包含配置文件名称和配置文件子命令的补全。

参数	描述
<shell>	要为其生成补全的 shell：bash、zsh 或 fish。

示例：

# 安装补全
hermes completion bash >> ~/.bashrc
hermes completion zsh >> ~/.zshrc
hermes completion fish > ~/.config/fish/completions/hermes.fish
 
# 重新加载 shell
source ~/.bashrc

安装后，Tab 补全可用于：

• hermes profile <TAB>——子命令（list、use、create 等）
• hermes profile use <TAB>——配置文件名称
• hermes -p <TAB>——配置文件名称

请参阅

• Profiles 用户指南
• CLI 命令参考
• FAQ — Profiles 部分