From 8a6deaaacf2f255b6581cc7f798a2e9df57f9987 Mon Sep 17 00:00:00 2001 From: Brooklyn Nicholson Date: Wed, 12 Aug 2026 12:57:18 -0500 Subject: [PATCH] docs: present /export and /import as the second way to share a profile MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The distributions guide framed export/import as local backup only, so the new slash commands read as a competing path instead of the lightweight half of one story. Give profile-distributions.md a comparison table up front (git repo vs single file: updates, versioning, setup cost, what each carries), rewrite the Not-a-fit bullets that mislabeled export, and add a full Export/import section covering the CLI, TUI, and desktop entry points, the desktop.json overlay, and what an archive actually contains — including that it can carry memories and sessions, which a distribution never does. Also register /export and /import in the slash-command reference (they shipped undocumented), point the profile-command entries at their chat and desktop doors, and cover the desktop Export/Import UI on the desktop page. --- website/docs/reference/profile-commands.md | 15 +-- website/docs/reference/slash-commands.md | 4 +- website/docs/user-guide/desktop.md | 1 + .../docs/user-guide/profile-distributions.md | 101 +++++++++++++++++- website/docs/user-guide/profiles.md | 22 +++- 5 files changed, 127 insertions(+), 16 deletions(-) diff --git a/website/docs/reference/profile-commands.md b/website/docs/reference/profile-commands.md index 24a8f6791b55a..1f13d8e03b278 100644 --- a/website/docs/reference/profile-commands.md +++ b/website/docs/reference/profile-commands.md @@ -248,7 +248,9 @@ hermes profile rename mybot assistant hermes profile export [options] ``` -Exports a profile as a compressed tar.gz archive. +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`](./slash-commands.md), 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. | Argument / Option | Description | |-------------------|-------------| @@ -264,13 +266,17 @@ hermes profile export work hermes profile export work -o ./work-2026-03-29.tar.gz ``` +See [Export and import a profile file](../user-guide/profile-distributions.md#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` ```bash hermes profile import [options] ``` -Imports a profile from a tar.gz archive. +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`](./slash-commands.md), 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. | Argument / Option | Description | |-------------------|-------------| @@ -305,10 +311,7 @@ The recipient's user data (memories, sessions, auth, their own edits to updates. :::info -`hermes profile export` / `import` are still the right commands for -**local backup and restore** of a profile on your own machine. Distribution -(`install` / `update` / `info`) is a separate concept: ship a profile via -git so someone else can install it. +Two ways to share a profile, and they complement each other. `hermes profile export` / `import` (also `/export` and `/import` in chat) produce a **single file** — no repo, no manifest, and a desktop export carries your theme and layout too. Distribution (`install` / `update` / `info`) publishes a profile as a **git repo** so recipients can pull versioned updates later. Backup and restore is the export file's other job. See [Two ways to share a profile](../user-guide/profile-distributions.md#two-ways-to-share-a-profile). ::: ### `hermes profile install` diff --git a/website/docs/reference/slash-commands.md b/website/docs/reference/slash-commands.md index c5f646fa6acb4..bbf996ac840f6 100644 --- a/website/docs/reference/slash-commands.md +++ b/website/docs/reference/slash-commands.md @@ -82,6 +82,8 @@ Type `/` in the CLI to open the autocomplete menu. Built-in commands are case-in | `/fast [normal\|fast\|status]` | Toggle fast mode — OpenAI Priority Processing / Anthropic Fast Mode. Options: `normal`, `fast`, `status`. | | `/reasoning [level\|show\|hide\|full\|clamp] [--global]` | Manage reasoning effort and display. Levels include `none` / `minimal` / `low` / `medium` / `high` / `xhigh` / `max` / `ultra`. `show` / `hide` (or `on` / `off`) toggle reasoning display; `full` and `clamp` adjust how reasoning is shown. `--global` persists effort to config. | | `/skin` | Show or change the display skin/theme | +| `/export [profile] [-o out.tar.gz]` | **CLI only.** Pack a profile into a shareable `.tar.gz` — skills, memory, persona, crons, plugins, settings, and (from the desktop) themes and layout. Credentials (`auth.json`, `.env`) are stripped. Defaults to the active profile and `.tar.gz` in the current directory. Same archive as `hermes profile export`; for a versioned, updatable share use a [profile distribution](../user-guide/profile-distributions.md) instead. | +| `/import [--name ]` | **CLI only.** Install a profile archive as a new profile, inferring the name from the archive unless `--name` is given. Refuses to overwrite an existing profile and cannot import as `default`. Creates a shell wrapper when the name is free. See [Export and import a profile file](../user-guide/profile-distributions.md#export-and-import-a-profile-file). | | `/statusbar` (alias: `/sb`) | Toggle the context/model status bar on or off | | `/battery [on\|off\|status]` | Toggle a color-coded battery read-out as the first status-bar element (off by default; no-op without a battery). | | `/voice [on\|off\|tts\|status]` | Toggle CLI voice mode and spoken playback. Recording uses `voice.record_key` (default: `Ctrl+B`). | @@ -285,7 +287,7 @@ The messaging gateway supports the following built-in commands inside Telegram, ## Notes -- `/skin`, `/snapshot`, `/reload`, `/tools`, `/toolsets`, `/browser`, `/config`, `/cron`, `/platforms`, `/paste`, `/image`, `/statusbar`, `/battery`, `/focus`, `/plugins`, `/busy`, `/indicator`, `/wake`, `/journey`, `/redraw`, `/clear`, `/history`, `/save`, `/copy`, `/handoff`, `/prompt`, `/pet`, `/hatch`, `/timestamps`, `/subscription`, and `/quit` are **CLI-only** commands. +- `/skin`, `/snapshot`, `/export`, `/import`, `/reload`, `/tools`, `/toolsets`, `/browser`, `/config`, `/cron`, `/platforms`, `/paste`, `/image`, `/statusbar`, `/battery`, `/focus`, `/plugins`, `/busy`, `/indicator`, `/wake`, `/journey`, `/redraw`, `/clear`, `/history`, `/save`, `/copy`, `/handoff`, `/prompt`, `/pet`, `/hatch`, `/timestamps`, `/subscription`, and `/quit` are **CLI-only** commands. - `/skills` is **CLI-only for search/browse/install**; its write-approval review subcommands (`pending`, `approve`, `reject`, `diff`, `approval`) also work on messaging platforms when `skills.write_approval` is on. `/memory` works on **both** surfaces. - `/verbose` is **CLI-only by default**, but can be enabled for messaging platforms by setting `display.tool_progress_command: true` in `config.yaml`. When enabled, it cycles the `display.tool_progress` mode and saves to config. - `/focus` and `/verbose` share one suppression path (`display.tool_progress`), so they can never contradict each other: `/focus on` pins tool progress to `off` and stashes your mode under `display.focus_saved_tool_progress`; `/focus off` restores it; cycling `/verbose` while focus is on takes the mode back and clears the focus badge. Focus view is display-only — it never changes conversation history, the system prompt, or anything sent to the model, so it has zero prompt-cache impact. diff --git a/website/docs/user-guide/desktop.md b/website/docs/user-guide/desktop.md index d7c803ed77bab..bfbdf249935b1 100644 --- a/website/docs/user-guide/desktop.md +++ b/website/docs/user-guide/desktop.md @@ -165,6 +165,7 @@ The app also surfaces the broader Hermes management surface so you don't have to - **Session-list overhaul** — a reworked session list with archiving and general session hygiene to keep the list manageable as it grows. - **Search sessions by id** — find a specific session directly by its id. - **Concurrent multi-profile sessions** — run sessions across multiple [profiles](./profiles.md) at the same time, and reference a session in another profile with cross-profile `@session` links. +- **Export / import a profile** — share a whole setup as a single file. **⌘K → Export profile…** (or right-click a profile square in the rail) writes a `.tar.gz` with skills, memory, persona, crons, plugins, and settings; API keys are stripped. Exporting from the desktop also bundles your appearance and interface — skin, light/dark mode, custom themes, the profile's rail color, and your window layout — so an imported profile arrives looking the way the sender had it. Import via **⌘K → Import profile…** or the button beside the rail's **+**; it applies the overlay and drops you into the new profile. The same archive works with `/export` / `/import` in chat and `hermes profile export` / `import` from a shell. See [Export and import a profile file](./profile-distributions.md#export-and-import-a-profile-file). ## Updating diff --git a/website/docs/user-guide/profile-distributions.md b/website/docs/user-guide/profile-distributions.md index 5a9da24850535..46f0660210962 100644 --- a/website/docs/user-guide/profile-distributions.md +++ b/website/docs/user-guide/profile-distributions.md @@ -8,6 +8,26 @@ A **profile distribution** packages a complete Hermes agent — personality, ski If a [profile](./profiles.md) is a local agent, a distribution is that agent made shareable. +## Two ways to share a profile + +Hermes has two sharing paths, and they answer different questions. Distributions are the durable one; export files are the quick one. + +| | **Distribution** (git repo) | **Export file** (`.tar.gz`) | +|---|---|---| +| Ship it by | `hermes profile install ` | Send a file — chat, AirDrop, USB, email | +| Recipient needs | git, and access to the repo | The file | +| Updates | `hermes profile update` pulls new versions | Re-send the file | +| Versioning | Tags, branches, commit SHAs | None — a snapshot in time | +| Setup cost for the author | `distribution.yaml` + `.gitignore` + a repo | None — one command | +| Carries | SOUL, config, skills, cron, MCP, plugins | The same, **plus** the desktop theme and layout | +| Made with | `hermes profile install` / `update` | `/export` and `/import`, or `hermes profile export` / `import` | + +Pick a **distribution** when the agent is a product you'll keep improving and other people should track: a team's reviewed internal agent, a community release, the same agent deployed to five machines. + +Pick an **export file** when you just want someone to have your setup right now, or you're moving to a new laptop. No repo, no manifest — run `/export` in chat, hand over the file, they run `/import`. See [Export and import a profile file](#export-and-import-a-profile-file). + +The two aren't exclusive. Plenty of authors dogfood a profile, `/export` it to a colleague for a second opinion, then publish it as a distribution once it's worth versioning. + ## What this means Before distributions, sharing a Hermes agent meant sending someone: @@ -65,9 +85,10 @@ Good fits: Not a fit: -- **You just want to back up a profile on your own machine.** Use [`hermes profile export` / `import`](../reference/profile-commands.md#hermes-profile-export) — that's what those are for. -- **You want to share API keys alongside the agent.** `auth.json` and `.env` are deliberately excluded from distributions. Each installer brings their own credentials. -- **You want to share memories / sessions / conversation history.** Those are user data, not distribution content. Never shipped. +- **You want to hand someone your setup once, right now.** A distribution needs a repo, a manifest, and a `.gitignore`. `/export` needs none of that — see [Export and import a profile file](#export-and-import-a-profile-file). Same for backing up or moving a profile to a new machine. +- **You want to share your desktop theme and layout.** A distribution carries the agent — SOUL, config, skills, cron, MCP, plugins. An export made from the desktop app also carries the look: skin, light/dark mode, custom themes, rail color, and window layout. +- **You want to share API keys alongside the agent.** `auth.json` and `.env` are deliberately excluded from distributions. Each installer brings their own credentials. (Export files strip them too.) +- **You want to share memories / sessions / conversation history.** Those are user data, not distribution content. Never shipped. (Export files are different here — read [what an export contains](#what-an-export-file-contains) before sending one.) :::caution **Hermes does not control git.** The file exclusions described on this page are applied by the **installer** when someone runs `hermes profile install` or `hermes profile update`. They are **not** applied when you run `git add` or `git commit`. @@ -594,6 +615,77 @@ hermes profile install ~/.hermes/profiles/research-bot --name research-bot-test --- +## Export and import a profile file + +When you don't need versioning, skip the repo. `/export` packs a profile into a single `.tar.gz`; `/import` unpacks it as a new profile on the other end. Credentials are stripped on the way out. + +### Export + +In the CLI, TUI, or desktop chat: + +``` +/export # the active profile → .tar.gz +/export research-bot # a named profile +/export research-bot -o ~/Desktop/research-bot.tar.gz +``` + +Or from a shell, same machinery: + +```bash +hermes profile export research-bot +hermes profile export research-bot -o ./research-bot.tar.gz +``` + +In the **desktop app** there are three doors, all landing on a native save dialog: + +- **⌘K → Export profile…** +- Right-click a profile square in the sidebar rail → **Export profile…** +- The import button beside the rail's **+** covers the other direction + +A desktop export adds one extra file the CLI doesn't: `desktop.json`, carrying your skin, light/dark mode, any custom theme definitions the skin needs, the profile's rail color, and your window layout. That's why a profile shared from the desktop arrives *looking* like yours, not just behaving like yours. + +### Import + +``` +/import ~/Downloads/research-bot.tar.gz +/import ~/Downloads/research-bot.tar.gz --name research-bot-2 +``` + +```bash +hermes profile import ./research-bot.tar.gz +hermes profile import ./research-bot.tar.gz --name research-bot-2 +``` + +The profile name is inferred from the archive unless you pass `--name`. Importing over an existing profile is refused — rename or delete the old one first. A shell wrapper (`research-bot` → `hermes -p research-bot`) is created when the name doesn't collide with an existing command. + +Importing in the desktop app also applies the `desktop.json` overlay and drops you into the new profile on a fresh chat. Importing a desktop-made archive from the CLI is fine — the overlay file rides along on disk and applies the next time you open that profile in the desktop. + +:::note +You cannot import as `default` — that name is the built-in root profile (`~/.hermes`). Pass `--name something-else`. +::: + +### What an export file contains + +Always excluded, both profiles types: `auth.json` and `.env`. Your API keys never leave the machine. + +**The default profile** (`~/.hermes`) is exported through an allow-list — only known Hermes artifacts, so an unrelated file sitting in your home directory can't get swept in: + +`config.yaml`, `SOUL.md`, `MEMORY.md`, `USER.md`, `todo.json`, `system_prompt.md`, `AGENTS.md`, `CLAUDE.md`, `.cursorrules`, `skills/`, `plugins/`, `cron/`, `scripts/`, `sessions/`, `memories/`, `knowledge/`, `preferences/`, and `desktop.json` when the desktop staged one. + +**A named profile** (`~/.hermes/profiles/`) copies the whole directory minus `auth.json` / `.env`. That's broader — if the profile has `state.db`, logs, or caches, they go in the archive too, and the file gets big. + +:::caution Read your archive before you send it +An export is a snapshot of your profile, not a curated release. Unlike a distribution, it **can** include `memories/`, `sessions/`, and `USER.md` — and nothing scans skills, memories, or your persona for anything personal you wrote into them. Credentials are filtered by filename; content is not. + +Before sharing with someone else, list what's inside: + +```bash +tar -tzf research-bot.tar.gz | less +``` + +If it carries conversation history you'd rather not hand over, publish a [distribution](#for-authors-publishing-a-distribution) instead — those never ship memories or sessions. +::: + ## What's NOT in a distribution (ever) The installer hard-excludes these paths even if an author accidentally ships them. No config option lets you override this — the safety guard is a regression-tested invariant: @@ -645,7 +737,8 @@ The short version: - [Profiles: Running Multiple Agents](./profiles.md) — the base concept - [Profile Commands reference](../reference/profile-commands.md) — every flag, every option -- [`hermes profile export` / `import`](../reference/profile-commands.md#hermes-profile-export) — local backup / restore (not distribution) +- [`hermes profile export` / `import`](../reference/profile-commands.md#hermes-profile-export) — the CLI form of [export files](#export-and-import-a-profile-file) +- [Slash Commands reference](../reference/slash-commands.md) — `/export`, `/import`, and every other in-chat command - [Using SOUL with Hermes](../guides/use-soul-with-hermes.md) — authoring personalities - [Personality & SOUL](./features/personality.md) — how SOUL fits into the agent - [Skills catalog](../reference/skills-catalog.md) — skills you can bundle diff --git a/website/docs/user-guide/profiles.md b/website/docs/user-guide/profiles.md index 9603f956749d0..cd68f1c4b7a08 100644 --- a/website/docs/user-guide/profiles.md +++ b/website/docs/user-guide/profiles.md @@ -241,10 +241,12 @@ User-modified skills are never overwritten. hermes profile list # show all profiles with status hermes profile show coder # detailed info for one profile hermes profile rename coder dev-bot # rename (updates alias + service) -hermes profile export coder # export to coder.tar.gz -hermes profile import coder.tar.gz # import from archive +hermes profile export coder # pack into coder.tar.gz (shareable; keys stripped) +hermes profile import coder.tar.gz # install an archive as a new profile ``` +In chat, the same two live as `/export` and `/import` — and in the desktop app as **⌘K → Export/Import profile…**. See [Sharing a profile](#sharing-a-profile). + ## Deleting a profile ```bash @@ -305,9 +307,19 @@ the actual account home when `home_mode: profile` is active. The default profile is simply `~/.hermes` itself. No migration needed — existing installs work identically. -## Sharing profiles as distributions +## Sharing a profile -A profile you built on one machine can be packaged as a **git repository** and installed with one command on another machine — your own workstation, a teammate's laptop, or a community user's environment. The shared package includes the SOUL, config, skills, cron jobs, and MCP connections. Credentials, memories, and sessions stay per-machine. +A profile you built on one machine can go to another — your own workstation, a teammate's laptop, or the community. Two paths: + +**Send a file.** `/export` packs the profile into one `.tar.gz` — skills, memory, persona, crons, plugins, settings, and (from the desktop) your theme and layout. API keys are stripped. The recipient runs `/import`. + +```bash +# In chat, run /export, hand over the file, and they run /import on it +hermes profile export coder +hermes profile import ./coder.tar.gz --name coder +``` + +**Publish a distribution.** Package the profile as a **git repository** so recipients install it with one command and pull versioned updates later. Carries the SOUL, config, skills, cron jobs, and MCP connections; credentials, memories, and sessions stay per-machine. ```bash # Install a whole agent from a git repo @@ -317,4 +329,4 @@ hermes profile install github.com/you/research-bot --alias hermes profile update research-bot ``` -See **[Profile Distributions: Share a Whole Agent](./profile-distributions.md)** for the full guide — authoring, publishing, update semantics, security model, and use cases. +Use an export file for a one-time handoff or a move; use a distribution for an agent you'll keep shipping. See **[Profile Distributions: Share a Whole Agent](./profile-distributions.md)** for both — the comparison table, authoring, publishing, update semantics, and the security model.