mirror of https://github.com/NousResearch/hermes-agent.git synced 2026-05-09 03:11:58 +00:00

feat(profile): shareable profile distributions via git (#20831 )

* feat(profile): shareable profile distributions (pack/install/update/info)

Closes #20456.

Turns a profile into a portable, versioned artifact. Packs SOUL.md, config,
skills, cron, and an env-var manifest into a tar.gz that others can install
from a local path, URL, or git repo. Updates re-pull the distribution while
preserving user data (memories, sessions, auth.json, .env) and the user's
config.yaml overrides.

New subcommands (under hermes profile, no parallel tree):
  hermes profile pack    <name> [-o FILE]
  hermes profile install <source> [--name N] [--alias] [--force] [-y]
  hermes profile update  <name> [--force-config] [-y]
  hermes profile info    <name>

Manifest (distribution.yaml at the profile root): name, version,
hermes_requires, author, env_requires, distribution_owned.

Security:
  - Installer shows manifest + env-var requirements before mutating disk;
    confirmation required unless -y.
  - auth.json and .env are never packed (same exclude set as profile export).
  - Cron jobs are packed but NOT auto-scheduled — user is pointed at
    'hermes -p <name> cron list' to review.
  - Archive extraction rejects path traversal (../ members).
  - Alias creation is opt-in via --alias.

Update semantics:
  - Distribution-owned paths (SOUL.md, skills/, cron/, mcp.json, manifest):
    replaced from the new archive.
  - config.yaml: preserved by default; --force-config to overwrite.
  - User-owned paths (memories/, sessions/, auth.json, .env, state.db*,
    logs/, workspace/, plans/, home/, *_cache/, local/): never touched.

Version pin:
  hermes_requires accepts >=, <=, ==, !=, >, < or a bare version (treated
  as >=). Install fails with a clear error when the running Hermes version
  doesn't satisfy the spec.

Sources supported by 'install':
  - Local .tar.gz / .tgz archive
  - Local directory
  - HTTP(S) URL pointing to a .tar.gz (uses httpx, already a dep)
  - Git URL (github.com/user/repo, https://..., git@..., ssh://, git://)

Tests: 43 new unit tests (manifest parsing, version checks, env template,
pack/install/update round-trip, config-preservation, security).
E2E validated via real CLI invocations against an isolated HERMES_HOME
covering pack, install with confirmation, update preservation, update
--force-config, decline-preview, duplicate-install rejection, and
version-requirement rejection.

* refactor(profile-dist): git-only — drop tar.gz/HTTP transports and pack

Scope-cut on top of the original distribution PR: a profile distribution
is now exclusively a git repository (or a local directory during
development). The tar.gz / HTTP archive transports and the matching
`hermes profile pack` subcommand have been removed.

Why:
* GitHub tags, branches, and commits are already the right versioning
  primitive. Tag pushes do for us what 'pack + upload' did.
* `hermes profile export` / `import` already cover local backup and
  restore; they are not a distribution format and stay untouched.
* One transport means one install/update code path, one doc page,
  and one mental model. The extra source types doubled the surface
  for no real user win — GitHub auto-attaches release tarballs, and
  `git bundle` / `git clone --mirror` cover the airgap case.

Changes:
* hermes_cli/profile_distribution.py — removed pack_profile,
  _fetch_tar_archive (_http_fetch), _safe_extract, _archive_roots,
  _safe_parts, _find_dist_root, tarfile/io/urlparse imports. The
  new _stage_source has two arms: git URL → clone, local directory
  → use in place.
* hermes_cli/main.py — removed the 'pack' subparser and action
  handler. Install help text updated to match the reduced source list.
* tests/hermes_cli/test_profile_distribution.py — rewritten around a
  local-directory staging fixture. The install/update/describe suites
  now build a distribution tree on disk directly and install from it,
  which is what a real git clone produces after .git is stripped.
  Dropped TestPack, TestFindDistRoot, and the tar-specific security
  test. New tests cover _looks_like_git_url, env_example emission,
  hermes_requires enforcement, and 'installer does not import
  credentials if an author mistakenly leaks them in the staging tree'.
* website/docs/reference/profile-commands.md — 'Distribution commands'
  section rewritten around git. Added a 'Publishing a distribution'
  section. export/import stay documented as local backup/restore.
* website/docs/reference/cli-commands.md — dropped 'pack' from the
  profile subcommand table.
* website/package.json — 'lint:diagrams' now passes
  --exclude-code-blocks to ascii-guard. Without it, markdown tables
  and box-drawing diagrams inside fenced code blocks were being
  misidentified as malformed ASCII boxes, blocking the PR's
  docs-site-checks CI with 8 false-positive errors.

Validation:
* Targeted suite: tests/hermes_cli/test_profile_distribution.py —
  56/56 pass (down from 43 — reorganized to cover the new
  local-dir paths).
* Regression: test_profiles.py + test_profile_export_credentials.py
  102/102 still pass. export/import behaviour unchanged.
* Docs lint: ascii-guard lint --exclude-code-blocks docs returns
  0 errors (was 8 on the PR before the flag bump).
* E2E: ran the real `hermes profile install`/`info` against a
  local staging dir under an isolated HERMES_HOME — install writes
  SOUL.md + skills to the target profile, info reads the manifest
  back, a bogus source produces a clear error, and `hermes profile
  pack` is now rejected by argparse as expected.

* feat(profile-dist): distribution-aware list/show/delete + installed_at + env preview

Polish pass on top of the git-only scope cut. Five additions, all small,
wiring into existing commands rather than adding new surface.

1. `installed_at` timestamp on the manifest
   * Stamped automatically inside plan_install() on both fresh install
     and update — ISO-8601 UTC, seconds resolution.
   * Surfaced in `hermes profile info` as `Installed:    <ts>`.
   * Lets users tell "installed 6 months ago, needs update" from
     "installed yesterday" without guessing from file mtimes.

2. `hermes profile list` grows a `Distribution` column
   * Plain profiles: "—"
   * Distribution profiles: "<name>@<version>" (e.g. `telemetry@1.2.3`)
   * ProfileInfo gains three optional fields — distribution_name,
     distribution_version, distribution_source — populated by a new
     _read_distribution_meta() helper that swallows manifest read errors
     so a broken distribution.yaml in one profile can't break `list`
     for the others.

3. `hermes profile show` and `hermes profile delete` surface
   distribution provenance
   * show: `Distribution: name@version` + `Installed from: <source>`
     plus a pointer to `hermes profile info <name>` for the full
     manifest.
   * delete: same lines in the pre-confirmation preview, so a user
     deleting "telemetry" can see it came from
     `github.com/kyle/telemetry-distribution` before they type
     `telemetry` to confirm. No change to the confirmation gate itself —
     deletion semantics are identical to plain profiles.

4. Install preview checks env vars against the current environment
   * Replaces the "Env vars you'll need to set:" header with a simpler
     "Env vars:" block.
   * Each required var is labeled:
     - `✓ set` — already in `os.environ` OR present as a key in the
       target profile's existing .env (update case).
     - `needs setting` — required but not found in either place.
     - `—` — optional.
   * Mirrors pip's "Requirement already satisfied" UX: no unnecessary
     nagging about keys the user already has configured.

5. Docs: private distributions
   * New "Private distributions" section in
     website/docs/reference/profile-commands.md explaining that we
     shell out to the user's `git` binary, so SSH keys / credential
     helpers / GitHub CLI stored creds all work transparently. One
     paragraph, two examples.
   * `hermes profile info` section updated to mention `Installed:`.

Module-level hoist:
* `from datetime import datetime, timezone` was previously lazy-imported
  inside plan_install(). Hoisted to module scope so tests can monkeypatch
  `hermes_cli.profile_distribution.datetime` to freeze time.

Tests (+7):
* TestInstalledAtStamp.test_install_stamps_installed_at — format check
  (4-digit year, 'T', +00:00 suffix).
* TestInstalledAtStamp.test_update_refreshes_installed_at — freezes
  datetime.now() to 2099-01-01 and confirms update writes a new stamp.
* TestProfileInfoDistribution.test_installed_distribution_shows_in_list
  — ProfileInfo.distribution_{name,version,source} populated after install.
* TestProfileInfoDistribution.test_plain_profile_has_no_distribution_fields
  — plain profiles have None.
* TestProfileInfoDistribution.test_malformed_manifest_does_not_break_list
  — broken distribution.yaml in one profile doesn't break list_profiles().

Validation:
* 163/163 tests pass (56 distribution + 102 profile regression +
  5 new from this commit — up from 158).
* docs-lint: 0 errors.
* E2E verified: install preview shows ✓/needs-setting per env var,
  `profile list` shows Distribution column, `profile show` + `delete`
  preview mentions source URL, `info` shows Installed: timestamp.

* fix(profile-dist): clean errors + warn when overwriting plain profiles

Two small polish fixes found during collision sweeps of the PR:

1. ValueError from validate_profile_name now caught cleanly
   * A distribution.yaml whose 'name' field can't be used as a profile
     identifier (spaces, path traversal, etc.) raises ValueError from
     hermes_cli.profiles.validate_profile_name, which was escaping as a
     raw Python traceback from 'hermes profile install/update/info'.
   * Broadened the except clause in all three handlers to catch
     (DistributionError, ValueError) — users now see:
       Error: Invalid profile name '../../etc/passwd'. Must match
              [a-z0-9][a-z0-9_-]{0,63}
     instead of a stack trace.

2. Install preview distinguishes plain profile overwrite from
   distribution re-install
   * When plan.target_dir exists and IS a distribution (has
     distribution.yaml), preview still shows the mild
       (profile exists — will overwrite distribution-owned files only)
   * When plan.target_dir exists but is a HAND-BUILT plain profile (no
     distribution.yaml), preview now shows a loud warning:
       ⚠ Profile exists but is NOT a distribution.  Installing here will
         overwrite its SOUL.md, skills/, cron/, and mcp.json.
         Your memories, sessions, auth.json, and .env will be preserved,
         but any hand-edits to distribution-owned files will be lost.
   * Users who type 'hermes profile install foo --force' against a
     profile they hand-built now see what they're signing up for. User
     data is still safe (memories, sessions, auth, .env are in
     USER_OWNED_EXCLUDE), but custom SOUL/skills get stomped.

Tests (+2):
* TestErrorSurfaces.test_bad_profile_name_raises_valueerror_not_traceback
* TestErrorSurfaces.test_path_traversal_name_rejected

Validation:
* 165/165 tests pass (was 163).
* E2E: bad manifest names produce 'Error: Invalid profile name ...'
  with no traceback; installing over a plain profile shows the warning;
  re-installing over an existing distribution shows the normal
  overwrite message.
* Bad HTTPS URLs still produce 'Error: git clone failed: ...' — git
  itself generates a clean enough message that no wrapper is needed.
* 'install .' works correctly from any cwd.

* fix(profiles): reject reserved names at validate time

Before: `hermes profile create hermes` / `profile install` / `profile rename`
all silently accepted reserved names like `hermes`, `test`, `tmp`, `root`,
`sudo`. The profile directory was created; only alias creation failed (via
check_alias_collision), leaving a confusingly-named profile on disk — e.g.
`~/.hermes/profiles/hermes/` sitting next to `~/.hermes/` itself.

The reserved set already exists (_RESERVED_NAMES, introduced alongside alias
collision detection). This commit moves the check up one layer to
validate_profile_name so every entry point — create, install, import,
rename, dashboard web API — shares the same gate.

The error message points the user at the cause without being cryptic:
  Error: Profile name 'hermes' is reserved — it collides with either the
  Hermes installation itself or a common system binary.  Pick a different
  name.

`default` continues to pass through (it's a special alias for ~/.hermes).
_HERMES_SUBCOMMANDS (`chat`, `model`, `gateway`, etc.) stays at
alias-collision time only — those are fine as bare profile names with
`--no-alias`.

Tests (+5): test_reserved_names_rejected parametrized over the full
_RESERVED_NAMES set, matching the existing pattern in TestValidateProfileName.

No existing test uses a reserved name as a profile identifier (greppped
create_profile("hermes|test|tmp|root|sudo") — zero hits).

Validation:
* 170/170 tests pass in the profile suites.
* E2E: `profile create hermes`, `profile install` with manifest
  name=hermes, and `profile install ... --name hermes` all produce the
  same clean `Error: Profile name 'hermes' is reserved ...` with rc=1
  and no traceback. Normal names (`mybot`) still work.

2026-05-08 10:04:32 -07:00

13 KiB

Raw Blame History

sidebar_position
7

Profile Commands Reference

This page covers all commands related to Hermes profiles. For general CLI commands, see CLI Commands Reference.

`hermes profile`

hermes profile <subcommand>

Top-level command for managing profiles. Running hermes profile without a subcommand shows help.

Subcommand	Description
`list`	List all profiles.
`use`	Set the active (default) profile.
`create`	Create a new profile.
`delete`	Delete a profile.
`show`	Show details about a profile.
`alias`	Regenerate the shell alias for a profile.
`rename`	Rename a profile.
`export`	Export a profile to a tar.gz archive.
`import`	Import a profile from a tar.gz archive.

`hermes profile list`

hermes profile list

Lists all profiles. The currently active profile is marked with *.

Example:

$ hermes profile list
  default
* work
  dev
  personal

No options.

`hermes profile use`

hermes profile use <name>

Sets <name> as the active profile. All subsequent hermes commands (without -p) will use this profile.

Argument	Description
`<name>`	Profile name to activate. Use `default` to return to the base profile.

Example:

hermes profile use work
hermes profile use default

`hermes profile create`

hermes profile create <name> [options]

Creates a new profile.

Argument / Option	Description
`<name>`	Name for the new profile. Must be a valid directory name (alphanumeric, hyphens, underscores).
`--clone`	Copy `config.yaml`, `.env`, and `SOUL.md` from the current profile.
`--clone-all`	Copy everything (config, memories, skills, sessions, state) from the current profile.
`--clone-from <profile>`	Clone from a specific profile instead of the current one. Used with `--clone` or `--clone-all`.
`--no-alias`	Skip wrapper script creation.

Creating a profile does not make that profile directory the default project/workspace directory for terminal commands. If you want a profile to start in a specific project, set terminal.cwd in that profile's config.yaml.

Examples:

# Blank profile — needs full setup
hermes profile create mybot

# Clone config only from current profile
hermes profile create work --clone

# Clone everything from current profile
hermes profile create backup --clone-all

# Clone config from a specific profile
hermes profile create work2 --clone --clone-from work

`hermes profile delete`

hermes profile delete <name> [options]

Deletes a profile and removes its shell alias.

Argument / Option	Description
`<name>`	Profile to delete.
`--yes`, `-y`	Skip confirmation prompt.

Example:

hermes profile delete mybot
hermes profile delete mybot --yes

:::warning This permanently deletes the profile's entire directory including all config, memories, sessions, and skills. Cannot delete the currently active profile. :::

`hermes profile show`

hermes profile show <name>

Displays details about a profile including its home directory, configured model, gateway status, skills count, and configuration file status.

This shows the profile's Hermes home directory, not the terminal working directory. Terminal commands start from terminal.cwd (or the launch directory on the local backend when cwd: ".").

Argument	Description
`<name>`	Profile to inspect.

Example:

$ 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]

Regenerates the shell alias script at ~/.local/bin/<name>. Useful if the alias was accidentally deleted or if you need to update it after moving your Hermes installation.

Argument / Option	Description
`<name>`	Profile to create/update the alias for.
`--remove`	Remove the wrapper script instead of creating it.
`--name <alias>`	Custom alias name (default: profile name).

Example:

hermes profile alias work
# Creates/updates ~/.local/bin/work

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

hermes profile alias work --remove
# Removes the wrapper script

`hermes profile rename`

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

Renames a profile. Updates the directory and shell alias.

Argument	Description
`<old-name>`	Current profile name.
`<new-name>`	New profile name.

Example:

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]

Exports a profile as a compressed tar.gz archive.

Argument / Option	Description
`<name>`	Profile to export.
`-o`, `--output <path>`	Output file path (default: `<name>.tar.gz`).

Example:

hermes profile export work
# Creates work.tar.gz in the current directory

hermes profile export work -o ./work-2026-03-29.tar.gz

`hermes profile import`

hermes profile import <archive> [options]

Imports a profile from a tar.gz archive.

Argument / Option	Description
`<archive>`	Path to the tar.gz archive to import.
`--name <name>`	Name for the imported profile (default: inferred from archive).

Example:

hermes profile import ./work-2026-03-29.tar.gz
# Infers profile name from the archive

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

Distribution commands

Distributions turn a profile into a shareable, versioned artifact published as a git repository. A recipient installs the distribution with a single command and can update it in place later without touching their local memories, sessions, or credentials.

auth.json and .env are never part of a distribution — they stay on the installing user's machine.

The recipient's user data (memories, sessions, auth, their own edits to .env) is always preserved across the initial install and subsequent updates.

:::info hermes profile export / import are still the right commands for local backup and restore of a profile on your own machine. Distribution (install / update / info) is a separate concept: ship a profile via git so someone else can install it. :::

`hermes profile install`

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

Installs a profile distribution from a git URL or a local directory.

Option	Description
`<source>`	Git URL (`github.com/user/repo`, `https://...`, `git@...`, `ssh://`, `git://`) or a local directory containing `distribution.yaml` at its root.
`--name NAME`	Override the profile name from the manifest.
`--alias`	Also create a shell wrapper (e.g. `telemetry` → `hermes -p telemetry`).
`--force`	Overwrite an existing profile of the same name. User data is still preserved.
`-y`, `--yes`	Skip the manifest-preview confirmation prompt.

The installer shows the manifest, lists required env vars, and warns about cron jobs before asking for confirmation. Required env vars go into a .env.EXAMPLE file you copy to .env and fill in.

Examples:

# Install from a GitHub repo (shorthand)
hermes profile install github.com/kyle/telemetry-distribution --alias

# Install from a full HTTPS git URL
hermes profile install https://github.com/kyle/telemetry-distribution.git

# Install from SSH
hermes profile install git@github.com:kyle/telemetry-distribution.git

# Install from a local directory during development
hermes profile install ./telemetry/

`hermes profile update`

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

Re-clones the distribution from its recorded source and applies updates. Distribution-owned files (SOUL.md, skills/, cron/, mcp.json) are overwritten; user data (memories, sessions, auth, .env) is never touched.

config.yaml is preserved by default to keep your local overrides. Pass --force-config to reset it to the distribution's shipped config.

`hermes profile info`

hermes profile info <name>

Prints the profile's distribution manifest — name, version, required Hermes version, author, env var requirements, the source URL/path, and the Installed: timestamp recorded when the distribution was last install-ed or update-d. Useful for checking what a shared profile needs before installing it, and for spotting "this profile was installed 6 months ago and hasn't been updated."

hermes profile list also shows the distribution name and version in a Distribution column, and hermes profile show <name> / delete <name> surface the source URL so you can tell at a glance which profiles came from a git repo vs. were created locally.

Private distributions

A private git repository works as a distribution source with no extra configuration — the install shells out to your normal git binary, so whatever authentication your shell is already set up for (SSH key, git credential helper, GitHub CLI's stored HTTPS credentials) applies transparently.

# Uses your SSH key, the same as any other `git clone`
hermes profile install git@github.com:your-org/internal-assistant.git

# Uses your git credential helper
hermes profile install https://github.com/your-org/internal-assistant.git

If a clone prompts for credentials interactively in your terminal during install, that prompt flows through. Set up your auth the way you'd normally use git clone against the same repo first, then install.

Distribution manifest (`distribution.yaml`)

Every distribution has a distribution.yaml at the root of its repository:

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:   # optional; defaults to SOUL.md, config.yaml,
                      #   mcp.json, skills/, cron/, distribution.yaml
  - SOUL.md
  - skills/compliance/
  - cron/

hermes_requires supports >=, <=, ==, !=, >, <, or a bare version (treated as >=). Install fails with a clear error if the current Hermes version doesn't satisfy the spec.

distribution_owned is optional. If set, only those paths are replaced on update; anything else in the profile stays user-owned. If omitted, the defaults above apply.

Publishing a distribution

Authoring a distribution is just a git push:

In your profile directory, create distribution.yaml with at least name and version.
Initialize a git repo (or use an existing one) and push to GitHub / GitLab / any host Hermes can clone from.
Tell recipients to run hermes profile install <your-repo-url>.

Use git tags for versioned releases — recipients who clone HEAD get your latest state, and you can always bump version: in the manifest.

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

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

Global flag to run any Hermes command under a specific profile without changing the sticky default. This overrides the active profile for the duration of the command.

Option	Description
`-p <name>`, `--profile <name>`	Profile to use for this command.

Examples:

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>

Generates shell completion scripts. Includes completions for profile names and profile subcommands.

Argument	Description
`<shell>`	Shell to generate completions for: `bash` or `zsh`.

Examples:

# Install completions
hermes completion bash >> ~/.bashrc
hermes completion zsh >> ~/.zshrc

# Reload shell
source ~/.bashrc

After installation, tab completion works for:

hermes profile <TAB> — subcommands (list, use, create, etc.)
hermes profile use <TAB> — profile names
hermes -p <TAB> — profile names

13 KiB Raw Blame History

Profile Commands Reference

hermes profile

hermes profile list

hermes profile use

hermes profile create

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

See also

13 KiB

Raw Blame History

`hermes profile`

`hermes profile list`

`hermes profile use`

`hermes profile create`

`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`