Skip to main content
How-to

Use the StoreFront CLI with Hermes Agent

Hermes Agent reads skills from its own home folder, not from the workspace, so its copy of the skill is installed there and shared by every workspace on the machine. Status: Supported.

Prerequisites​

  • Node.js 24 or newer, with npm, on the machine or container where Hermes runs its terminal commands.
  • Hermes Agent installed. init --target hermes needs to know the Hermes home (see below).
  • An UltraCart account whose user has StoreFront access.

Install the CLI​

npm install -g @ultracart/storefront-cli@beta
uc-storefront --version

On the official Hermes Agent Docker image, npm installs into the image's bundled Node, whose global bin folder is not on PATH. If uc-storefront is then "not found", link it:

ln -s "$(npm prefix -g)/bin/uc-storefront" /usr/local/bin/uc-storefront

Install the skill​

uc-storefront init my-storefront --target hermes --no-input
cd my-storefront
uc-storefront skills status

init prints the Hermes home it used, for example Hermes home: /opt/data (from HERMES_HOME). The skill goes to <Hermes home>/skills/build-ultracart-storefronts. The CLI finds the Hermes home in this order:

  1. --hermes-home <path> (an absolute path)
  2. $HERMES_HOME (/opt/data in the official Docker image, so the skill lands in /opt/data/skills)
  3. the profile named in ~/.hermes/active_profile, other than default
  4. ~/.hermes, or %LOCALAPPDATA%\hermes on Windows

Hermes trusts skills in its home without a security scan.

--hermes-home is not saved. If you used it, pass it again on every refresh and status check:

uc-storefront skills install --hermes-home /path/to/hermes-home
uc-storefront skills status --hermes-home /path/to/hermes-home

--target all includes Hermes only when $HERMES_HOME is set or a Hermes home already exists. Otherwise it prints a warning and skips Hermes; use --target hermes to install anyway.

Confirm Hermes sees the skill​

  1. uc-storefront skills status lists the Hermes copy with no missing or edited files.
  2. Ask Hermes to list its skills and look for build-ultracart-storefronts.

If the skill does not appear, check the pitfalls below before reinstalling.

Pitfalls that hide the skill​

  • A trusted workspace copy shadows the Hermes copy. If the workspace also has a .agents/skills copy (from --target codex or --target gemini) and the workspace is in Hermes's skills.trusted_project_dirs, Hermes prefers the workspace copy and scans it. Its security scan may quarantine that copy, which hides both. Leave the workspace untrusted in Hermes, or drop the codex and gemini targets. init and skills status print a note when this combination is possible.
  • Do not point skills.external_dirs at the installed npm package. Hermes skips every skill whose path contains node_modules, with no warning, so the skill never appears. Use init --target hermes instead.
  • Hermes can edit its own skills. Hermes agents may patch skills with skill_manage. If skills install stops because owned skill files were edited, compare the edits before you reinstall.
  • The copy is shared. Every workspace on the machine that selects hermes uses the same copy. Removing hermes from one workspace removes it for all of them; reinstall it from any workspace that still uses it.

Sign in​

Where the sign-in goes depends on the machine Hermes runs on, not on Hermes. On a machine with an operating system keychain, such as a Mac, a Windows PC or a Linux desktop with Secret Service, the CLI keeps the sign-in in that keychain and you do not need a credential key. The credential key steps below are only for Hermes in a container or cloud environment with no keychain.

Run uc-storefront auth status in the workspace first and read the credential store: line.

  • A keychain store (macos-keychain, windows-credential-manager or linux-secret-service): no key is needed. Skip to Check the key and sign in.
  • encrypted-file: Hermes is running where there is no keychain. Set up the credential key first.

Give Hermes the credential key (containers and cloud only)​

Hermes saves each terminal session's exported variables (export -p) to $HERMES_HOME/cache/scratch/hermes-snap-*.sh. A key passed as an environment variable therefore ends up on disk next to the encrypted sign-in it unlocks. Prefer a key file:

  1. On the host, create the key in a file on storage other than the sign-in's volume. This never displays it:

    umask 077; openssl rand -base64 32 > /path/outside/the/volume/uc-storefront.key
  2. Pass only the path to Hermes: ULTRACART_STOREFRONT_CREDENTIAL_KEY_FILE=/path/outside/the/volume/uc-storefront.key, through the Hermes home's .env file with the name listed in terminal.env_passthrough in config.yaml. The file must be a regular file owned by the user the CLI runs as, mode 0400 or 0600.

If the key itself has to go in the .env file, add ULTRACART_STOREFRONT_CREDENTIAL_KEY=<key> there with an editor (or a secret-source plugin), list the name in terminal.env_passthrough, and keep $HERMES_HOME/cache/scratch off persistent storage. In a container, link that folder to a folder in the container's own filesystem. Never set both variables; the CLI refuses that with credential_key_conflict.

Restart the Hermes session so its commands see the variable. The Hermes home already persists, so ULTRACART_STOREFRONT_CONFIG_DIR is usually not needed.

Check the key and sign in​

uc-storefront auth status
uc-storefront profile create my-store
uc-storefront auth login --profile my-store --no-wait
uc-storefront auth login --profile my-store --continue --wait
uc-storefront profile bind my-store
uc-storefront auth status
  • On a machine with a keychain, the first auth status shows a keychain store and no key is needed. In a container or cloud, it should show credential key: set (file) or set (environment). Before a profile exists it also refuses and exits 1; read the credential lines anyway.
  • auth login --no-wait prints a URL and a code and exits at once. Hermes relays both to you, and you approve in your own browser.
  • auth login --continue --wait waits up to 45 seconds. Exit 3 means still waiting: Hermes runs it again until it exits 0.
  • The last auth status should show local grant: present, with the keychain store or encrypted-file.

credential key: absent means the variable is not reaching Hermes's shell: check the name in terminal.env_passthrough and restart. unsafe_file means the key file is not a private regular file.

Talk to Hermes from Telegram or Slack​

Many merchants reach their Hermes Agent through a messaging app rather than a terminal, for example a Telegram group or a Slack channel connected through Hermes's messaging gateway. Hermes Agent's own documentation covers connecting a platform. With the StoreFront CLI, a few things change when the conversation happens in a shared chat:

  • Sign-in and approval links appear in the chat. Hermes relays the sign-in URL and code, address approvals and approval requests for risky changes as messages. Everyone in the group or channel can see them. Approving still needs your UltraCart login and authenticator app, but keep the chat limited to people you trust.
  • Anyone who can message the agent can ask it for changes. Changes that are risky or reach customers still wait for your approval in UltraCart, but drafts, previews and changes to inactive themes do not. Use a private group or channel, limited to the people who should direct work on the store.
  • Secrets never go in the chat. The credential key and any password belong in the Hermes home's configuration on the host, never in a Telegram or Slack message. If one is posted, replace it.
  • Approve on your own device. Open approval links in your own browser and approve with your authenticator app. Do not ask the agent, or anyone else in the chat, to approve for you.

Run Hermes on a dedicated machine​

Hermes works well on a small, always-on computer at your home or office, for example an older Mac mini you no longer use. A machine like that gives you both things the CLI wants:

  • A keychain. On a desktop operating system the sign-in goes into the keychain, so you need no credential key. On Linux, check that uc-storefront auth status shows linux-secret-service. Some Linux setups keep the keyring locked after a restart until someone logs in, and the CLI cannot use a locked keyring.
  • A stable address. The machine's outgoing address is your home or office connection, so you approve it once. See Approved addresses and a stable IP.

Pair it with Telegram or Slack, and you can reach the agent from anywhere while it runs, and signs in, from that one machine.

Next steps​

Was this page helpful?