Profile Commands Reference

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

hermes profile <subcommand>

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

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

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

Example:

hermes profile use work
hermes profile use default

hermes profile create <name> [options]

Creates a new profile.

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 [<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).

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 <name> [options]

Deletes a profile and removes its shell alias.

Example:

hermes profile delete mybot
hermes profile delete mybot --yes

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: ".").

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

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 <old-name> <new-name>

Renames a profile. Updates the directory and shell alias.

Example:

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

hermes profile export <name> [options]

Exports a profile as a compressed tar.gz archive — a portable snapshot you can back up, move to another machine, or hand to someone else. auth.json and .env are always excluded.

Also available in chat as /export, and in the desktop app via ⌘K → Export profile… or a profile square's right-click menu. A desktop export additionally stages desktop.json (skin, light/dark mode, custom themes, rail color, window layout) into the archive.

Example:

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

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

See Export and import a profile file for exactly what lands in the archive and what to check before sending one to someone else.

hermes profile import <archive> [options]

Imports a profile from a tar.gz archive, as a new profile. Refuses to overwrite an existing profile, and cannot import as default (the built-in root profile) — pass --name in either case. A shell wrapper is created when the name doesn't collide with an existing command.

Also available in chat as /import, and in the desktop app via ⌘K → Import profile… or the import button beside the profile rail's +. A desktop import also applies any bundled desktop.json overlay (theme, layout) and switches you into the new profile.

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

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.

hermes profile install

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

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

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:

1. In your profile directory, create distribution.yaml with at least name and version.
2. Initialize a git repo (or use an existing one) and push to GitHub / GitLab / any host Hermes can clone from.
3. 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 <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.

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

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

Examples:

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

# 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

• Profiles User Guide
• CLI Commands Reference
• FAQ — Profiles section