Profile Commands Reference

本頁面涵蓋所有與 Hermes profiles 相關的命令。一般 CLI 命令請參見 CLI Commands Reference。

`hermes profile`

hermes profile <subcommand>

管理 profiles 的頂層命令。不加子命令執行 hermes profile 會顯示說明。

子命令	描述
`list`	列出所有 profiles。
`use`	設定活躍（預設）profile。
`create`	建立新 profile。
`describe`	讀取或設定 profile 的描述（供 kanban orchestrator 用於路由）。
`delete`	刪除 profile。
`show`	顯示 profile 的詳細資訊。
`alias`	重新產生 profile 的 shell 別名。
`rename`	重新命名 profile。
`export`	將 profile 匯出為 tar.gz 壓縮檔。
`import`	從 tar.gz 壓縮檔匯入 profile。
`install`	從 git URL 或本機目錄安裝 profile distribution。參見 Profile Distributions。
`update`	重新拉取 distribution 管理的 profile 並重新套用其 bundle。
`info`	顯示 profile 的 distribution 中繼資料（來源 URL、commit、上次更新時間）。

`hermes profile list`

hermes profile list

列出所有 profiles。當前活躍的 profile 以 * 標記。

範例：

$ hermes profile list
  default
* work
  dev
  personal

無選項。

`hermes profile use`

hermes profile use <name>

將 <name> 設為活躍 profile。所有後續的 hermes 命令（不加 -p）都會使用此 profile。

參數	描述
`<name>`	要啟用的 profile 名稱。使用 `default` 可返回基礎 profile。

範例：

hermes profile use work
hermes profile use default

`hermes profile create`

hermes profile create <name> [options]

建立新 profile。

參數 / 選項	描述
`<name>`	新 profile 的名稱。必須是有效的目錄名稱（字母數字、連字號、底線）。
`--clone`	從當前 profile 複製 `config.yaml`、`.env`、`SOUL.md` 和 skills。
`--clone-all`	從當前 profile 複製所有內容（config、memories、skills、cron、plugins）。不包含逐 profile 的歷史：sessions、`state.db`、 backups、state-snapshots、checkpoints。
`--clone-from <profile>`	從特定 profile（而非當前的）複製 config/skills/SOUL。除非搭配 `--clone-all`，否則隱含 `--clone`。
`--no-alias`	跳過 wrapper 腳本的建立。
`--description "<text>"`	一到兩句描述此 profile 的用途。供 kanban orchestrator 根據角色（而非僅凭 profile 名稱）路由任務。可跳過並稍後透過 `hermes profile describe` 新增。持久化在 `<profile_dir>/profile.yaml` 中。
`--no-skills`	建立一個空的 profile，不啟用任何內建 skills。在 profile 中寫入 `.no-bundled-skills` 標記，以便未來的 `hermes update` 不會重新植入內建 skills，且不允許與 `--clone`、`--clone-from` 或 `--clone-all` 結合使用（這些仍會複製 skills）。適用於需要精簡 orchestrator profiles 或不應繼承完整 skill 目錄的沙箱 profiles。若要在已建立的 profile（包括預設的 `~/.hermes`）上切換此設定，使用 `hermes skills opt-out` / `hermes skills opt-in`。

建立 profile 不會將該 profile 目錄設為終端機命令的預設專案/工作目錄。若要讓 profile 從特定專案開始，在該 profile 的 config.yaml 中設定 terminal.cwd。

範例：

# 空白 profile — 需要完整設定
hermes profile create mybot

# 從當前 profile 複製 config
hermes profile create work --clone

# 從當前 profile 複製所有內容
hermes profile create backup --clone-all

# 從特定 profile 複製 config
hermes profile create work2 --clone-from work

# 從特定 profile 複製所有內容
hermes profile create work2-backup --clone-from work --clone-all

`hermes profile describe`

hermes profile describe [<name>] [options]

讀取或設定 profile 的描述。描述供 kanban orchestrator 用於根據每個 profile 的專長路由任務，而非僅凭 profile 名稱猜測。持久化在 <profile_dir>/profile.yaml 中，因此重啟後仍會保留，且可與 gateway 共享。

不加任何標誌時，顯示當前描述（若為空則顯示 (no description set for '<name>')）。

參數 / 選項	描述
`<name>`	要描述的 profile。除非使用 `--all --auto`，否則必填。
`--text "<text>"`	將描述設為此精確文字（使用者撰寫）。覆蓋任何現有描述。
`--auto`	透過輔助 LLM 自動產生 1-2 句描述，基於 profile 的已安裝 skills、設定的模型和名稱。在 `config.yaml` 的 `auxiliary.profile_describer` 下設定模型。自動產生的描述會標記 `description_auto: true`，以便儀表板標記需要審核。
`--overwrite`	搭配 `--auto` 使用時，也替換使用者撰寫的描述（預設：跳過已明確設定描述的 profiles）。
`--all`	搭配 `--auto` 使用時，掃描所有缺少描述的 profiles。

範例：

# 讀取當前描述
hermes profile describe researcher

# 明確設定
hermes profile describe researcher --text "Reads source code and writes findings."

# 讓 LLM 自動產生
hermes profile describe researcher --auto

# 為所有缺少描述的 profiles 填入描述
hermes profile describe --all --auto

`hermes profile delete`

hermes profile delete <name> [options]

刪除 profile 並移除其 shell 別名。

參數 / 選項	描述
`<name>`	要刪除的 profile。
`--yes`、`-y`	跳過確認提示。

範例：

hermes profile delete mybot
hermes profile delete mybot --yes

WARNING

這會永久刪除 profile 的完整目錄，包含所有設定、記憶、sessions 和 skills。無法刪除當前活躍的 profile。

`hermes profile show`

hermes profile show <name>

顯示 profile 的詳細資訊，包括其主目錄、設定的模型、gateway 狀態、skills 數量和設定檔狀態。

這裡顯示的是 profile 的 Hermes 主目錄，而非終端機工作目錄。終端機命令從 terminal.cwd（或當 cwd: "." 時本地後端的啟動目錄）開始。

參數	描述
`<name>`	要檢視的 profile。

範例：

$ 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>`	要建立/更新別名的 profile。
`--remove`	移除 wrapper 腳本而非建立。
`--name <alias>`	自訂別名名稱（預設：profile 名稱）。

範例：

hermes profile alias work
# 建立/更新 ~/.local/bin/work

hermes profile alias work --name mywork
# 建立 ~/.local/bin/mywork

hermes profile alias work --remove
# 移除 wrapper 腳本

`hermes profile rename`

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

重新命名 profile。更新目錄和 shell 別名。

參數	描述
`<old-name>`	目前的 profile 名稱。
`<new-name>`	新的 profile 名稱。

範例：

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]

將 profile 匯出為壓縮的 tar.gz 壓縮檔。

參數 / 選項	描述
`<name>`	要匯出的 profile。
`-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 壓縮檔匯入 profile。

參數 / 選項	描述
`<archive>`	要匯入的 tar.gz 壓縮檔路徑。
`--name <name>`	匯入 profile 的名稱（預設：從壓縮檔推斷）。

範例：

hermes profile import ./work-2026-03-29.tar.gz
# 從壓縮檔推斷 profile 名稱

hermes profile import ./work-2026-03-29.tar.gz --name work-restored

Distribution commands

TIP

不熟悉 distributions？ 請先閱讀 Profile Distributions 使用指南 — 它涵蓋了原因、時機和方法，包含完整範例。以下各節是乾燥的 CLI 參考，適用於你已知道需要什麼的情況。

Distributions 將 profile 轉換為可分享、版本化的工件，以 git repository 的形式發布。接收者只需一個命令即可安裝 distribution，且之後可以原地更新而不影響其本地的記憶、sessions 或憑證。

auth.json 和 .env 永遠不會成為 distribution 的一部分 — 它們保留在安裝者的機器上。

接收者的使用者資料（記憶、sessions、auth、對 .env 的自行編輯）在初始安裝和後續更新中都會始終保留。

INFO

hermes profile export / import 仍然是在本機備份和還原 profile 的正確命令。Distribution（install / update / info）是另一個概念：透過 git 分發 profile，以便其他人可以安裝它。

`hermes profile install`

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

從 git URL 或本機目錄安裝 profile distribution。

選項	描述
`<source>`	Git URL（`github.com/user/repo`、`https://...`、`git@...`、`ssh://`、`git://`）或包含 `distribution.yaml` 的本機目錄。
`--name NAME`	覆蓋 manifest 中的 profile 名稱。
`--alias`	同時建立 shell wrapper（例如 `telemetry` → `hermes -p telemetry`）。
`--force`	覆蓋同名的現有 profile。使用者資料仍會保留。
`-y`、`--yes`	跳過 manifest 預覽確認提示。

安裝程式會顯示 manifest、列出必要的環境變數，並在要求確認前警告排程任務。必要的環境變數會放入 .env.EXAMPLE 檔案，你需要複製為 .env 並填入。

範例：

# 從 GitHub repo 安裝（簡寫）
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]

從記錄的來源重新 clone distribution 並套用更新。Distribution 擁有的檔案（SOUL.md、skills/、cron/、mcp.json）會被覆蓋；使用者資料（記憶、sessions、auth、.env）永遠不會被觸碰。

config.yaml 預設會保留以維持你的本機覆寫。加上 --force-config 可將其重設為 distribution 隨附的設定。

`hermes profile info`

hermes profile info <name>

顯示 profile 的 distribution manifest — 名稱、版本、所需的 Hermes 版本、作者、環境變數需求、來源 URL/路徑，以及記錄 distribution 最後一次 install 或 update 時的 Installed: 時間戳記。在安裝共享 profile 前檢查其需求，以及偵測「此 profile 是 6 個月前安裝的且從未更新」都很有用。

hermes profile list 也會在 Distribution 欄位中顯示 distribution 名稱和版本，hermes profile show <name> / delete <name> 會顯示來源 URL，讓你一眼就能分辨哪些 profiles 來自 git repo、哪些是本機建立的。

Private distributions

私人 git repository 可直接作為 distribution 來源使用，無需額外設定 — 安裝程式會呼叫你一般的 git 程式，因此你 shell 已設定的任何驗證方式（SSH 金鑰、git credential helper、GitHub CLI 儲存的 HTTPS 憑證）都會透明套用。

# 使用你的 SSH 金鑰，與其他任何 `git clone` 相同
hermes profile install git@github.com:your-org/internal-assistant.git

# 使用你的 git credential helper
hermes profile install https://github.com/your-org/internal-assistant.git

如果在安裝期間 clone 提示你在終端機中互動式輸入憑證，該提示會直接傳遞。先設定好你通常用來 git clone 同一 repo 的驗證方式，然後再安裝。

Distribution manifest（`distribution.yaml`）

每個 distribution 在其 repository 根目錄都有一個 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 為可選。若設定，更新時只有這些路徑會被替換；profile 中的其他內容保持使用者擁有。若省略，則使用上述預設值。

Publishing a distribution

撰寫 distribution 只是 git push：

在你的 profile 目錄中建立 distribution.yaml，至少包含 name 和 version。
初始化 git repo（或使用現有的）並推送到 GitHub / GitLab / 任何 Hermes 可以 clone 的主機。
告訴接收者執行 hermes profile install <your-repo-url>。

使用 git 標籤進行版本化發布 — clone HEAD 的接收者會取得你的最新狀態，你也可以隨時在 manifest 中增加 version:。

`hermes -p` / `hermes --profile`

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

全域標誌，可在不改變固定預設的情況下以特定 profile 執行任何 Hermes 命令。這會在命令持續期間覆蓋活躍 profile。

選項	描述
`-p <name>`、`--profile <name>`	此命令使用的 profile。

範例：

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 自動完成腳本。包含 profile 名稱和 profile 子命令的完成。

參數	描述
`<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> — profile 名稱
hermes -p <TAB> — profile 名稱

Profile Commands Reference

hermes profile

hermes profile list

hermes profile use

hermes profile create

hermes profile describe

hermes profile delete

hermes profile show

hermes profile alias

hermes profile rename

hermes profile export

hermes profile import

Distribution commands

hermes profile install

hermes profile update

hermes profile info

Private distributions

Distribution manifest（distribution.yaml）

Publishing a distribution

hermes -p / hermes --profile

hermes completion

參見

Environment Variables

`hermes profile`

`hermes profile list`

`hermes profile use`

`hermes profile create`

`hermes profile describe`

`hermes profile delete`

`hermes profile show`

`hermes profile alias`

`hermes profile rename`

`hermes profile export`

`hermes profile import`

`hermes profile install`

`hermes profile update`

`hermes profile info`

Distribution manifest（`distribution.yaml`）

`hermes -p` / `hermes --profile`

`hermes completion`