docs: present /export and /import as the second way to share a profile (#84668)
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.
This commit is contained in:
brooklyn!
GitHub
commit
6aaa181f0e
|
|
@ -248,7 +248,9 @@ hermes profile rename mybot assistant
|
|||
hermes profile export <name> [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 <archive> [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`
|
||||
|
|
|
|||
|
|
@ -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 `<name>.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 <archive.tar.gz> [--name <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.
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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 <repo>` | 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 → <name>.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/<name>`) 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
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
Loading…
Reference in New Issue