Documentação oficial desta página · v0.20.6
Referência dos comandos de perfil
Referência dos comandos de perfil
Esta página cobre todos os comandos relacionados aos perfis do Hermes. Para os comandos gerais da CLI, veja a Referência dos comandos da CLI.
hermes profile
hermes profile <subcommand>
Comando de nível mais alto para gerenciar perfis. Rodar hermes profile sem subcomando mostra a
ajuda.
| Subcomando | Descrição |
|---|---|
list | Lista todos os perfis. |
use | Define o perfil ativo (padrão). |
create | Cria um perfil novo. |
describe | Lê ou define a descrição de um perfil (usada pelo orquestrador do kanban para rotear). |
delete | Apaga um perfil. |
show | Mostra detalhes de um perfil. |
alias | Gera de novo o alias de shell de um perfil. |
rename | Renomeia um perfil. |
export | Exporta um perfil para um arquivo tar.gz. |
import | Importa um perfil de um arquivo tar.gz. |
install | Instala uma distribuição de perfil a partir de uma URL git ou de um diretório local. Veja Distribuições de perfil. |
update | Baixa de novo um perfil gerenciado por distribuição e reaplica o pacote dele. |
info | Mostra os metadados de distribuição de um perfil (URL de origem, commit, última atualização). |
hermes profile list
hermes profile list
Lista todos os perfis. O perfil ativo no momento é marcado com *.
Exemplo:
$ hermes profile list
default
* work
dev
personal
Sem opções.
hermes profile use
hermes profile use <name>
Define <name> como o perfil ativo. Todos os comandos hermes seguintes (sem -p) vão usar este
perfil.
| Argumento | Descrição |
|---|---|
<name> | Nome do perfil a ativar. Use default para voltar ao perfil base. |
Exemplo:
hermes profile use work
hermes profile use default
hermes profile create
hermes profile create <name> [options]
Cria um perfil novo.
| Argumento / Opção | Descrição |
|---|---|
<name> | Nome do novo perfil. Precisa ser um nome de diretório válido (alfanumérico, hifens, sublinhados). |
--clone | Copia config.yaml, .env, SOUL.md e as skills do perfil atual. |
--clone-all | Copia tudo (configuração, memórias, skills, cron, plugins) do perfil atual. Exclui o histórico por perfil: sessões, state.db, backups, instantâneos de estado e checkpoints. |
--clone-from <profile> | Clona configuração/skills/SOUL de um perfil específico, em vez do atual. Implica --clone, a menos que venha junto com --clone-all. |
--no-alias | Pula a criação do script invólucro. |
--description "<text>" | Descrição de uma ou duas frases sobre no que este perfil é bom. Usada pelo orquestrador do kanban para rotear tarefas pelo papel, e não só pelo nome do perfil. Você pode pular e acrescentar depois com hermes profile describe. Persistida em <profile_dir>/profile.yaml. |
--no-skills | Cria um perfil vazio, com zero skills de fábrica habilitadas. Escreve um marcador .no-bundled-skills dentro do perfil, para que futuras execuções de hermes update não semeiem de novo o conjunto de fábrica, e se recusa a ser combinada com --clone, --clone-from ou --clone-all (que copiariam skills de qualquer jeito). Útil para perfis de orquestrador estreitos ou perfis de sandbox que não devem herdar o catálogo inteiro de skills. Para ligar/desligar isso num perfil já criado (inclusive no ~/.hermes padrão), use hermes skills opt-out / hermes skills opt-in. |
Criar um perfil não faz o diretório desse perfil virar o diretório de projeto/espaço de trabalho
padrão dos comandos de terminal. Se você quer que um perfil comece num projeto específico, defina
terminal.cwd no config.yaml desse perfil.
Exemplos:
# Perfil em branco — precisa de configuração completa
hermes profile create mybot
# Clona só a configuração do perfil atual
hermes profile create work --clone
# Clona tudo do perfil atual
hermes profile create backup --clone-all
# Clona a configuração de um perfil específico
hermes profile create work2 --clone-from work
# Clona tudo de um perfil específico
hermes profile create work2-backup --clone-from work --clone-all
hermes profile describe
hermes profile describe [<name>] [options]
Lê ou define a descrição de um perfil. A descrição é consumida pelo orquestrador do kanban para
rotear tarefas com base no que cada perfil faz bem, em vez de adivinhar só pelo nome do perfil. É
persistida em <profile_dir>/profile.yaml, então sobrevive a reinicializações e é compartilhada com
o gateway.
Sem opções, imprime a descrição atual (ou (no description set for '<name>'), se estiver vazia).
| Argumento / Opção | Descrição |
|---|---|
<name> | Perfil a descrever. Obrigatório, a menos que você use --all --auto. |
--text "<text>" | Define a descrição exatamente com este texto (escrito por você). Sobrescreve qualquer descrição existente. |
--auto | Gera automaticamente uma descrição de 1 a 2 frases pelo LLM auxiliar, com base nas skills instaladas, no modelo configurado e no nome do perfil. Configure o modelo em auxiliary.profile_describer, no config.yaml. As descrições geradas automaticamente são marcadas com description_auto: true, para o painel poder sinalizá-las para revisão. |
--overwrite | Junto com --auto, substitui também as descrições escritas por você (padrão: pular perfis cuja descrição foi definida explicitamente). |
--all | Junto com --auto, varre todos os perfis sem descrição. |
Exemplos:
# Lê a descrição atual
hermes profile describe researcher
# Define explicitamente
hermes profile describe researcher --text "Lê código-fonte e escreve as descobertas."
# Deixa o LLM gerar uma
hermes profile describe researcher --auto
# Preenche a descrição de todo perfil que não tem uma
hermes profile describe --all --auto
hermes profile delete
hermes profile delete <name> [options]
Apaga um perfil e remove o alias de shell dele.
| Argumento / Opção | Descrição |
|---|---|
<name> | Perfil a apagar. |
--yes, -y | Pula a confirmação. |
Exemplo:
hermes profile delete mybot
hermes profile delete mybot --yes
Isto apaga permanentemente o diretório inteiro do perfil, incluindo toda a configuração, memórias,
sessões e skills. O perfil default (~/.hermes) não pode ser apagado — use hermes uninstall
para remover tudo.
hermes profile show
hermes profile show <name>
Mostra detalhes de um perfil, incluindo o diretório de origem dele, o modelo configurado, o status do gateway, a contagem de skills e o status do arquivo de configuração.
Isso mostra o diretório de origem do Hermes daquele perfil, e não o diretório de trabalho do
terminal. Os comandos de terminal começam em terminal.cwd (ou no diretório de onde você chamou,
no backend local, quando cwd: ".").
| Argumento | Descrição |
|---|---|
<name> | Perfil a inspecionar. |
Exemplo:
$ 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
hermes profile alias <name> [options]
Gera de novo o script de alias de shell em ~/.local/bin/<name>. Útil se o alias foi apagado sem
querer, ou se você precisa atualizá-lo depois de mover a sua instalação do Hermes.
| Argumento / Opção | Descrição |
|---|---|
<name> | Perfil para o qual criar/atualizar o alias. |
--remove | Remove o script invólucro em vez de criá-lo. |
--name <alias> | Nome de alias personalizado (padrão: nome do perfil). |
Exemplo:
hermes profile alias work
# Cria/atualiza ~/.local/bin/work
hermes profile alias work --name mywork
# Cria ~/.local/bin/mywork
hermes profile alias work --remove
# Remove o script invólucro
hermes profile rename
hermes profile rename <old-name> <new-name>
Renomeia um perfil. Atualiza o diretório e o alias de shell.
| Argumento | Descrição |
|---|---|
<old-name> | Nome atual do perfil. |
<new-name> | Nome novo do perfil. |
Exemplo:
hermes profile rename mybot assistant
# ~/.hermes/profiles/mybot → ~/.hermes/profiles/assistant
# ~/.local/bin/mybot → ~/.local/bin/assistant
hermes profile export
hermes profile export <name> [options]
Exporta um perfil como um arquivo tar.gz comprimido — um instantâneo portátil que você pode guardar
como backup, levar para outra máquina ou entregar a outra pessoa. auth.json e .env são sempre
excluídos.
Também está disponível no chat como /export, e no aplicativo desktop em
⌘K → Export profile… ou pelo menu de clique direito do quadrado de um perfil. Um export pelo
desktop ainda coloca no arquivo o desktop.json (skin, modo claro/escuro, temas personalizados, cor
da barra, layout da janela).
| Argumento / Opção | Descrição |
|---|---|
<name> | Perfil a exportar. |
-o, --output <path> | Caminho do arquivo de saída (padrão: <name>.tar.gz). |
Exemplo:
hermes profile export work
# Cria work.tar.gz no diretório atual
hermes profile export work -o ./work-2026-03-29.tar.gz
Veja Exportar e importar um arquivo de perfil para saber exatamente o que vai parar no arquivo e o que conferir antes de mandá-lo para alguém.
hermes profile import
hermes profile import <archive> [options]
Importa um perfil de um arquivo tar.gz, como um perfil novo. Ele se recusa a sobrescrever um perfil
existente, e não consegue importar como default (o perfil raiz embutido) — passe --name nos dois
casos. Um invólucro de shell é criado quando o nome não colide com um comando existente.
Também está disponível no chat como /import, e no aplicativo desktop em
⌘K → Import profile… ou pelo botão de importar ao lado do + da barra de perfis. Um import
pelo desktop também aplica qualquer sobreposição desktop.json que venha junto (tema, layout) e
troca você para o novo perfil.
| Argumento / Opção | Descrição |
|---|---|
<archive> | Caminho do arquivo tar.gz a importar. |
--name <name> | Nome do perfil importado (padrão: inferido do arquivo). |
Exemplo:
hermes profile import ./work-2026-03-29.tar.gz
# Infere o nome do perfil a partir do arquivo
hermes profile import ./work-2026-03-29.tar.gz --name work-restored
Comandos de distribuição
Novidade em distribuições? Comece pelo guia de distribuições de perfil — ele cobre o porquê, o quando e o como, com exemplos completos. As seções abaixo são uma referência seca de CLI, para quando você já sabe o que quer.
Distribuições transformam um perfil num artefato compartilhável e versionado, publicado como um repositório git. Quem recebe instala a distribuição com um único comando e pode atualizá-la no lugar depois, sem mexer nas memórias, sessões ou credenciais locais.
auth.json e .env nunca fazem parte de uma distribuição — eles ficam na máquina de quem instala.
Os dados de quem instala (memórias, sessões, autenticação, as edições dele no .env) são sempre
preservados na instalação inicial e nas atualizações seguintes.
São dois jeitos de compartilhar um perfil, e eles se complementam. O hermes profile export /
import (também /export e /import no chat) produzem um arquivo único — sem repositório, sem
manifesto, e um export pelo desktop leva junto o seu tema e o seu layout. A distribuição (install
/ update / info) publica um perfil como um repositório git, para quem recebe poder baixar
atualizações versionadas depois. Fazer backup e restaurar é a outra função do arquivo de export.
Veja
Dois jeitos de compartilhar um perfil.
hermes profile install
hermes profile install <source> [--name <name>] [--alias] [--force] [--yes]
Instala uma distribuição de perfil a partir de uma URL git ou de um diretório local.
| Opção | Descrição |
|---|---|
<source> | URL git (github.com/user/repo, https://..., git@..., ssh://, git://) ou um diretório local com um distribution.yaml na raiz. |
--name NAME | Sobrepõe o nome de perfil que está no manifesto. |
--alias | Também cria um invólucro de shell (por exemplo, telemetry → hermes -p telemetry). |
--force | Sobrescreve um perfil existente com o mesmo nome. Os dados do usuário continuam preservados. |
-y, --yes | Pula a confirmação de prévia do manifesto. |
O instalador mostra o manifesto, lista as variáveis de ambiente obrigatórias e avisa sobre tarefas
de cron antes de pedir confirmação. As variáveis de ambiente obrigatórias vão para um arquivo
.env.EXAMPLE, que você copia para .env e preenche.
Exemplos:
# Instala de um repositório do GitHub (forma curta)
hermes profile install github.com/kyle/telemetry-distribution --alias
# Instala de uma URL git HTTPS completa
hermes profile install https://github.com/kyle/telemetry-distribution.git
# Instala por SSH
hermes profile install git@github.com:kyle/telemetry-distribution.git
# Instala de um diretório local, durante o desenvolvimento
hermes profile install ./telemetry/
hermes profile update
hermes profile update <name> [--force-config] [--yes]
Clona de novo a distribuição a partir da origem registrada e aplica as atualizações. Os arquivos que pertencem à distribuição (SOUL.md, skills/, cron/, mcp.json) são sobrescritos; os dados do usuário (memórias, sessões, autenticação, .env) nunca são tocados.
O config.yaml é preservado por padrão, para manter os seus overrides locais. Passe
--force-config para redefini-lo com a configuração que veio na distribuição.
hermes profile info
hermes profile info <name>
Imprime o manifesto de distribuição do perfil — nome, versão, versão exigida do Hermes, autor,
exigências de variáveis de ambiente, a URL/caminho de origem e o carimbo Installed:, registrado na
última vez em que a distribuição foi instalada (install) ou atualizada (update). Útil para
conferir do que um perfil compartilhado precisa antes de instalar, e para perceber aquele "este
perfil foi instalado há 6 meses e nunca foi atualizado".
O hermes profile list também mostra o nome e a versão da distribuição numa coluna Distribution,
e o hermes profile show <name> / delete <name> exibem a URL de origem, para você saber de bate
pronto quais perfis vieram de um repositório git e quais foram criados localmente.
Distribuições privadas
Um repositório git privado funciona como origem de distribuição sem nenhuma configuração extra — a
instalação chama o seu binário git normal, então qualquer autenticação que o seu shell já tenha
configurada (chave SSH, helper de git credential, credenciais HTTPS guardadas pela CLI do GitHub)
vale de forma transparente.
# Usa a sua chave SSH, igual a qualquer outro `git clone`
hermes profile install git@github.com:your-org/internal-assistant.git
# Usa o seu helper de credencial do git
hermes profile install https://github.com/your-org/internal-assistant.git
Se um clone pedir credenciais de forma interativa no seu terminal durante a instalação, esse pedido
aparece normalmente. Configure a sua autenticação do jeito que você normalmente usaria o
git clone no mesmo repositório e só então instale.
Manifesto de distribuição (distribution.yaml)
Toda distribuição tem um distribution.yaml na raiz do repositório:
name: telemetry
version: 0.1.0
description: "Arcabouço de monitoramento de conformidade"
hermes_requires: ">=0.12.0"
author: "Seu Nome"
license: "MIT"
env_requires:
- name: OPENAI_API_KEY
description: "Chave de API da OpenAI"
required: true
- name: GRAPHITI_MCP_URL
description: "URL do grafo de memória"
required: false
default: "http://127.0.0.1:8000/sse"
distribution_owned: # opcional; o padrão é SOUL.md, config.yaml,
# mcp.json, skills/, cron/, distribution.yaml
- SOUL.md
- skills/compliance/
- cron/
hermes_requires aceita >=, <=, ==, !=, >, <, ou uma versão pura (tratada como >=). A
instalação falha com um erro claro se a versão atual do Hermes não satisfizer a especificação.
distribution_owned é opcional. Se estiver definido, só esses caminhos são substituídos na
atualização; todo o resto do perfil continua pertencendo ao usuário. Se for omitido, valem os
padrões acima.
Publicar uma distribuição
Criar uma distribuição é só um git push:
- No diretório do seu perfil, crie um
distribution.yamlcom pelo menosnameeversion. - Inicialize um repositório git (ou use um existente) e faça push para o GitHub / GitLab / qualquer host de onde o Hermes consiga clonar.
- Diga a quem for receber para rodar
hermes profile install <your-repo-url>.
Use tags do git para releases versionados — quem clona o HEAD pega o seu estado mais recente, e
você sempre pode subir o version: no manifesto.
hermes -p / hermes --profile
hermes -p <name> <command> [options]
hermes --profile <name> <command> [options]
Opção global para rodar qualquer comando do Hermes sob um perfil específico, sem mudar o padrão fixo. Ela sobrepõe o perfil ativo pela duração do comando.
| Opção | Descrição |
|---|---|
-p <name>, --profile <name> | Perfil a usar neste comando. |
Exemplos:
hermes -p work chat -q "Verifique o status do servidor"
hermes --profile dev gateway start
hermes -p personal skills list
hermes -p work config edit
hermes completion
hermes completion <shell>
Gera scripts de autocompletar do shell. Inclui o autocompletar de nomes de perfil e de subcomandos de perfil.
| Argumento | Descrição |
|---|---|
<shell> | Shell para o qual gerar o autocompletar: bash, zsh ou fish. |
Exemplos:
# Instala o autocompletar
hermes completion bash >> ~/.bashrc
hermes completion zsh >> ~/.zshrc
hermes completion fish > ~/.config/fish/completions/hermes.fish
# Recarrega o shell
source ~/.bashrc
Depois de instalado, o autocompletar por tab funciona para:
hermes profile <TAB>— subcomandos (list, use, create etc.)hermes profile use <TAB>— nomes de perfilhermes -p <TAB>— nomes de perfil