`hermes config set` vs Direct Edit

+15 Mana ✨
hermes config Subcommands(DOCUMENTATION)

Introduction

Hermes offers two ways to change configuration: the hermes config set KEY VALUE command, and opening config.yaml (or .env) in your editor. Both end up writing to the same files, but they fit different moments. set is faster for one specific change. Direct edit is better when you want to restructure, comment, or change related settings together. Picking the right one keeps your config tidy.

Key Concepts

  • hermes config set: One-line CLI command that writes a single value.
  • hermes config edit: Opens config.yaml in $EDITOR for free-form changes.
  • Smart routing: set automatically routes secrets to .env and non-secrets to config.yaml.
  • hermes config check / migrate: Verify completeness and add new options after Hermes updates.

Real World Context

A developer wants to switch their default model. hermes config set model anthropic/claude-opus-4. Done in two seconds. The same developer, a week later, wants to add a new provider, configure its base URL, set a fallback chain, and adjust compression. They run hermes config edit, open Neovim with the YAML file, and make all six changes coherently with comments. The two flows complement each other: surgical changes go through set, structural changes go through direct edit.

Deep Dive

hermes config set

The set command takes a key path (dot-separated for nesting) and a value:

bash
hermes config set model anthropic/claude-opus-4
hermes config set terminal.backend docker
hermes config set display.busy_input_mode steer
hermes config set memory.max_tokens 200000

The command is smart enough to handle two specific situations:

  • Secrets land in .env: hermes config set OPENROUTER_API_KEY sk-or-... writes to .env automatically, not to config.yaml. The router looks at the key name (_API_KEY, _TOKEN, _PASSWORD patterns) and routes accordingly.
  • Non-secrets land in config.yaml: Everything else lands in the YAML file, creating the nested structure if it does not exist.

This routing means you can use set for both kinds of values without thinking about which file you are writing to. Just name the key.

hermes config edit

When you have more than one related change, or when you want to add comments, edit is better. It opens config.yaml in $EDITOR:

bash
hermes config edit
# opens ~/.hermes/config.yaml in your editor
# make any changes you want
# save and quit
# Hermes reloads the config on the next session

Use this when:

  • You are restructuring (moving keys, renaming, reorganizing).
  • You want to add a comment explaining a non-obvious choice.
  • You are changing multiple related keys together (e.g., terminal backend plus Docker env forwarding plus compression).
  • You want to see your whole config in context.

hermes config check and migrate

When Hermes ships an update that adds new config keys, your existing config will work, but you may be missing useful new defaults. The check and migrate commands handle this:

bash
hermes config check    # reports what is missing or stale
hermes config migrate  # interactively adds the missing keys with safe defaults

Run these after every major Hermes update. They are cheap and they keep your config aligned with the runtime.

When configuration changes take effect

Most changes apply to the next session, not the running one. Editing config.yaml while a session is open is fine, but do not be surprised when the running session still uses the old value. To pick up changes, either start a new session, or use the corresponding slash command (/model, /tools, etc.) inside the running session.

Common Pitfalls

  1. Using set for multiple related changes: It works, but you end up with a config that lacks structural coherence. Open the file instead.
  2. Expecting live reload during a running session: Most config changes apply at session start. For mid-session changes, use slash commands.

Best Practices

  1. Use set for surgical, one-off changes: Fast, safe, no editor required.
  2. Use edit for anything more than one change: Maintains structure and lets you comment.
  3. Run config check after every Hermes update: Cheap insurance against missing new defaults.

Summary

  • hermes config set is the right tool for one-off changes; it routes secrets to .env automatically.
  • hermes config edit is the right tool for multi-change or structural edits.
  • hermes config check and migrate keep your config aligned after Hermes updates.
  • Most changes apply at the next session start; use slash commands for live changes.

Code Examples

bash
# Surgical change with smart routing
hermes config set model anthropic/claude-opus-4         # → config.yaml
hermes config set terminal.backend docker               # → config.yaml
hermes config set OPENROUTER_API_KEY sk-or-abc123       # → .env (smart routing)

# Structural change: open the file in $EDITOR
hermes config edit
# rearrange, comment, change multiple related keys, save, quit

# After a Hermes update, top up any missing defaults
hermes config check       # what's missing?
hermes config migrate     # add it interactively with safe defaults
✓ Completed