hermes profile Command — Complete Reference & Examples

Overview

hermes profile manages multiple isolated Hermes instances. Each profile has its own configuration, sessions, skills, memory, and credentials. Profiles are stored under ~/.hermes/profiles/<name>/. The default profile always exists.

Use the global --profile <name> (or -p) flag to run a single command against a different profile without changing the sticky default.

hermes profile <subcommand>

Subcommands

list

List all profiles.

hermes profile list

use <name>

Set the sticky default profile.

hermes profile use work

create <name>

Create a new profile. Profile names should be lowercase and alphanumeric.

hermes profile create work [--clone] [--clone-all] [--clone-from SOURCE] [--no-alias] [--no-skills] [--description "Work tasks"]

Flags:

• --clone — Copy config.yaml, .env, SOUL.md, and skills from the active profile.
• --clone-all — Full copy of the active profile (all state except per-profile history).
• --clone-from SOURCE — Copy from a specific source profile (implies --clone unless --clone-all is set).
• --no-alias — Skip wrapper-script creation.
• --no-skills — Create an empty profile with no bundled skills.
• --description — One- or two-sentence description used by the kanban decomposer.

delete <name>

Delete a profile and all its data.

hermes profile delete old-project [-y]

describe [name]

Read or set a profile’s description.

hermes profile describe work --text "Backend-focused work profile"
hermes profile describe --auto --all

Flags:

• --text TEXT — Set description to exact text.
• --auto — Auto-generate description via the auxiliary LLM.
• --overwrite — With --auto, replace existing descriptions too.
• --all — With --auto, sweep every profile missing a description.

show <name>

Show profile details.

hermes profile show work

alias <profile_name>

Manage wrapper scripts for a profile.

hermes profile alias work [--name work-hermes]
hermes profile alias work --remove

rename <old_name> <new_name>

Rename a profile.

hermes profile rename work company-x

export <name>

Export a profile to a .tar.gz archive.

hermes profile export work -o work.tar.gz

import <archive>

Import a profile from a .tar.gz archive.

hermes profile import work.tar.gz [--name work]

install <source>

Install a Hermes profile distribution from a git URL (e.g. github.com/user/repo, https://..., git@...) or a local directory containing distribution.yaml at its root.

hermes profile install https://github.com/org/profile-dist [--name work] [--alias] [--force] [-y]

Flags:

• --name NAME — Override profile name from the manifest.
• --alias — Create a shell wrapper alias.
• --force — Overwrite an existing profile of the same name (user data preserved).
• -y — Skip manifest preview confirmation.

update <name>

Re-pull the distribution from its recorded source and apply updates. User data (memories, sessions, auth, .env) is preserved; config.yaml is preserved unless --force-config is used.

hermes profile update work [--force-config] [-y]

info <name>

Show a profile’s distribution manifest (version, requirements, source).

hermes profile info work

Examples

# Create and switch to a work profile
hermes profile create work --description "Backend work"
hermes profile use work

# One-shot command in another profile without switching
hermes --profile personal chat -q "Plan my weekend"

# Export and later re-import a profile
hermes profile export work -o work-backup.tar.gz
hermes profile import work-backup.tar.gz --name work-restored

# Install a shared team profile distribution
hermes profile install [email protected]:org/team-hermes-profile --alias -y

# Update a distribution-backed profile
hermes profile update team-profile -y

Tips

• Profiles are fully isolated: configs, sessions, auth, and memory do not leak between them.
• Use hermes --profile <name> ... for one-off commands without changing the default.
• describe --auto --all is handy before using kanban, because the decomposer uses descriptions to route tasks.
• Distribution installs (install/update) preserve user data and only overwrite distribution-owned files by default.