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. |
describe | Read or set a profile's description (used by the kanban orchestrator for routing). |
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. |
install | Install a profile distribution from a git URL or local directory. See Profile Distributions. |
update | Re-pull a distribution-managed profile and re-apply its bundle. |
info | Show distribution metadata for a profile (origin URL, commit, last update). |
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, SOUL.md, and skills from the current profile. |
--clone-all | Copy everything (config, memories, skills, cron, plugins) from the current profile. Excludes per-profile history: sessions, state.db, backups, state-snapshots, checkpoints. |
--clone-from <profile> | Clone config/skills/SOUL from a specific profile instead of the current one. Implies --clone unless paired with --clone-all. |
--no-alias | Skip wrapper script creation. |
--description "<text>" | One- or two-sentence description of what this profile is good at. Used by the kanban orchestrator to route tasks based on role instead of profile name alone. Skip and add later via hermes profile describe. Persisted in <profile_dir>/profile.yaml. |
--no-skills | Create an empty profile with zero bundled skills enabled. Writes a .no-bundled-skills marker into the profile so future hermes update runs won't re-seed the bundled set, and refuses to combine with --clone, --clone-from, or --clone-all (which would copy skills in anyway). Useful for narrow orchestrator profiles or sandbox profiles that should not inherit the full skill catalog. To toggle this on an already-created profile (including the default ~/.hermes), use hermes skills opt-out / hermes skills opt-in. |
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-from work
# Clone everything from a specific profile
hermes profile create work2-backup --clone-from work --clone-all
hermes profile describe
hermes profile describe [<name>] [options]
Read or set a profile's description. The description is consumed by the kanban orchestrator to route tasks based on what each profile is good at, rather than guessing from the profile name alone. Persisted in <profile_dir>/profile.yaml so it survives reboots and is shared with the gateway.
With no flags, prints the current description (or (no description set for '<name>') if empty).
| Argument / Option | Description |
|---|---|
<name> | Profile to describe. Required unless --all --auto is used. |
--text "<text>" | Set the description to this exact text (user-authored). Overwrites any existing description. |
--auto | Auto-generate a 1-2 sentence description via the auxiliary LLM, based on the profile's installed skills, configured model, and name. Configure the model under auxiliary.profile_describer in config.yaml. Auto-generated descriptions are marked description_auto: true so the dashboard can flag them for review. |
--overwrite | With --auto, replace user-authored descriptions too (default: skip profiles whose description was set explicitly). |
--all | With --auto, sweep every profile missing a description. |
Examples:
# Read the current description
hermes profile describe researcher
# Set it explicitly
hermes profile describe researcher --text "Reads source code and writes findings."
# Let the LLM generate one
hermes profile describe researcher --auto
# Fill in descriptions for every profile that doesn't have one
hermes profile describe --all --auto
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
This permanently deletes the profile's entire directory including all config, memories, sessions, and skills. The default profile (~/.hermes) cannot be deleted — use hermes uninstall to remove everything.
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