Comandos Herdr Core

O comando hc opera os terminais do Herdr Core, também usados pelo Herdr Desktop. Consulte os grupos abaixo para localizar a sintaxe e a finalidade de cada ação. O comando herdr pertence ao Herdr TUI e tem uma referência separada.

Substitua os valores entre <...> pelos nomes, caminhos ou textos do seu ambiente. Os colchetes indicam opções e a barra vertical separa alternativas. Esses marcadores explicam a sintaxe e não devem ser copiados literalmente.

Ajuda e seleção do terminal

Sem subcomando, hc apresenta um seletor de terminais em uma sessão interativa. Use hc --help para conferir a sintaxe da versão instalada e hc --skill para imprimir as instruções para agentes.

1
hc
2
hc --help
3
hc --version
4
hc --licenses
5
hc --skill
6
hc <comando> --help

O alvo <terminal> aceita um endereço como t7, um nome ou um endereço remoto como servidor/t7. Use o endereço retornado na sua execução. Em um terminal interativo, alguns comandos abrem um seletor quando o alvo é omitido. Em scripts, informe o alvo para tornar o destino explícito.

Os comandos aceitam --json. A saída direcionada a um pipe usa JSON por padrão, com exceções como run e read, que imprimem texto. -V equivale a --version e -h equivale a --help. A variável HC_SESSION seleciona uma sessão do Herdr Core e HC_TERMINAL_ID identifica o terminal atual dentro dele.

Execução de programas e templates

run

Cria um terminal e inicia o programa ou template indicado. Sem programa, abre o shell da máquina escolhida. Por padrão, acompanha a saída e espera o programa. Use --bg para retornar ao terminal de origem logo após iniciar.

1
hc run [--name <nome>] [--cwd <diretorio>] [--on <maquina>] [--bg] [--timeout <segundos>] [<programa> <argumentos>...]
2
hc run [--bg] <template> "<tarefa>"

O nome aceita de 1 a 32 caracteres entre letras minúsculas, números, hífen e sublinhado e deve ser único entre os terminais ativos. Localmente, o diretório padrão é aquele onde você executa hc. Com --on, o padrão é a pasta pessoal da máquina remota. Os caminhos informados em --cwd precisam existir na máquina de execução.

O timeout de espera usa wait_timeout da configuração ou 180 segundos. Ao atingir esse tempo, a espera retorna e o programa pode continuar executando. Isso é diferente do timeout de hc exec, que encerra a execução.

templates

Lista os templates disponíveis para hc run. Um template descreve o comando e as instruções iniciais do agente, que precisa estar instalado separadamente.

1
hc templates

No Linux e no macOS, o diretório padrão é ~/.config/herdr-core/templates. No Windows, é %APPDATA%\herdr-core\templates. XDG_CONFIG_HOME pode alterar esse local. Um template remoto precisa existir na máquina remota. Templates e comandos de shell entre aspas exigem sh no PATH do Windows.

Consulta e acesso aos terminais

ls

Lista os terminais ativos. --all inclui os encerrados e cada --label acrescenta uma condição de filtro.

1
hc ls [--all] [--label <chave=valor>]

get

Mostra o estado de um terminal. O Herdr Core registra o estado informado pelo programa pelo protocolo OSC 7501, sem deduzi-lo pelo texto da tela.

1
hc get [<terminal>]

attach

Conecta sua interface ao terminal escolhido. --observe permite acompanhar sem enviar entrada nem alterar o tamanho. --history define quantas linhas anteriores serão mostradas inicialmente, com padrão zero na tela principal.

1
hc attach [<terminal>] [--observe] [--history <linhas>]

Use Ctrl+\ para desconectar a visualização e manter o programa em execução. Encerrar o programa dentro do terminal tem outro efeito e pode finalizar a tarefa.

read

Imprime a tela atual e o histórico solicitado. --lines acrescenta linhas anteriores à tela, com padrão zero, e não limita o resultado inteiro a esse número.

1
hc read [<terminal>] [--lines <linhas>]

label

Define etiquetas no terminal. Informe chave= para remover uma etiqueta existente.

1
hc label <terminal> <chave=valor> [<outra=valor>...]

Entrada e acompanhamento dos agentes

send

Envia texto ao terminal e aciona Enter. Confirme o programa e a tela que receberão a mensagem, pois a entrada pode responder a uma conversa ou a um diálogo aberto.

1
hc send <terminal> "<texto>" [--if idle|working] [--force] [--wait] [--timeout <segundos>]

--if só envia quando o estado corresponde ao valor informado. --force permite o envio mesmo quando o programa aguarda uma intervenção. Com --wait, acompanha o turno iniciado pelo envio. O timeout usa a configuração ou 180 segundos e não comprova que a tarefa terminou.

keys

Envia as teclas nomeadas para o programa. A sequência pode incluir enter, esc, tab, up, ctrl+c, alt+x e f5.

1
hc keys <terminal> <tecla> [<outra-tecla>...]

interrupt

Envia a tecla de interrupção configurada e relata o efeito observado. A espera padrão é de 10 segundos. Confira a saída para saber se o programa parou ou se ainda aguarda uma resposta.

1
hc interrupt [<terminal>] [--timeout <segundos>]

wait

Espera uma mudança no terminal ou nos auxiliares. Pode retornar por conclusão, solicitação de atenção, erro, encerramento, mensagem ao principal ou timeout. Leia a razão retornada e a saída do programa.

1
hc wait [<terminal>] [--timeout <segundos>]
2
hc wait [<terminal-principal>] --children any|all [--timeout <segundos>]
3
hc wait <terminal> --output "<texto>" [--timeout <segundos>]

--children all espera até nenhum auxiliar estar trabalhando. Um auxiliar sem estado informado ainda é considerado em trabalho nessa espera. --children any retorna a próxima notícia relevante ou uma mensagem ao principal. Sem alvo, a seleção dos auxiliares usa o terminal que executa o comando.

--output procura texto impresso depois do início da espera. Uma ocorrência antiga na tela não satisfaz essa condição. O timeout padrão usa a configuração ou 180 segundos, mantendo o programa ativo quando a espera termina por tempo.

events

Acompanha mudanças ao vivo e produz uma linha JSON por evento quando a saída vai para um pipe. Os filtros restringem os eventos ao terminal, aos seus auxiliares ou às etiquetas indicadas.

1
hc events [--terminal <terminal>] [--children-of <principal>] [--label <chave=valor>]

Encerramento e recuperação

kill

Encerra o programa do terminal, começando por um sinal de desconexão e aumentando a intervenção quando necessário. Isso termina a execução e não equivale a sair de attach.

1
hc kill [<terminal>]

rm

Remove o registro de um terminal já encerrado. Para um programa ainda ativo, confira o alvo e encerre sua execução primeiro.

1
hc rm [<terminal>]

keep

Ativa a recuperação de um terminal ativo após a perda do programa. A recuperação abre um shell novo e não repete o comando original. Uma saída normal ou um encerramento explícito continua finalizando o programa.

1
hc keep <terminal>
2
hc keep <terminal> --off

--off desativa a recuperação. Os fluxos abertos terminam quando ocorre a perda. Conecte novamente após o estado restarted.

Comandos e arquivos sem terminal

exec

Executa um programa sem criar um terminal, reproduzindo sua saída e seu código de encerramento. Os argumentos são executados diretamente, sem interpretação por um shell.

1
hc exec [--on <maquina>] [--cwd <diretorio>] [--env <chave=valor>] [--timeout <segundos>] [-i] <programa> [<argumentos>...]

-i ou --stdin encaminha a entrada recebida por pipe. --env pode ser repetido e acrescenta valores ao ambiente do Herdr Core. O timeout padrão é 60 segundos, com máximo de 600, e encerra o programa e os processos iniciados por ele.

file read

Imprime um arquivo de texto ou parte dele. A primeira linha é 1. Sem --limit, lê até o limite de 8 MB.

1
hc file read <caminho> [--on <maquina>] [--cwd <diretorio>] [--offset <linha>] [--limit <linhas>]

file write

Substitui o conteúdo do arquivo pela entrada recebida e cria diretórios ausentes. Confira o destino, pois o conteúdo anterior será substituído.

1
hc file write <caminho> [--on <maquina>] [--cwd <diretorio>] < arquivo-local.txt

file edit

Substitui um texto exato encontrado uma única vez no arquivo. Os pares --old e --new podem ser repetidos na mesma ordem. Todas as substituições precisam ser válidas para a edição ser aplicada.

1
hc file edit <caminho> --old "<texto-antigo>" --new "<texto-novo>" [--on <maquina>] [--cwd <diretorio>]

Nos comandos de arquivo, caminhos relativos partem do diretório atual quando executados localmente. Com --on, partem da pasta pessoal remota, salvo uso de --cwd. Pela API, o diretório padrão é o do Herdr Core.

put

Envia um arquivo local para junto do terminal na máquina correspondente e imprime o caminho de destino. O nome do arquivo é preservado, incluindo sua extensão.

1
hc put <terminal> <arquivo-local>

Máquinas remotas

machine add

Cadastra uma máquina acessível por SSH. O destino aceita um host configurado no SSH ou um endereço com usuário. --name define o nome local da conexão, usando o host como padrão.

1
hc machine add [<destino-ssh>] [--name <nome>] [--session <sessao>] [--install] [--temp]
2
hc machine add --name <nome> --via "<comando-de-conexao>" [--session <sessao>]

A máquina remota precisa do Herdr Core. --install autoriza copiar a instalação quando ausente ou incompatível, sem confirmação interativa. --session seleciona a sessão remota, usando a padrão quando omitido. --temp identifica uma máquina temporária, mas não a remove automaticamente.

--via exige --name e um comando que transporte a entrada e a saída sem alterações nem perguntas interativas. No Windows, use chaves SSH ou um agente SSH, pois esse caminho não compartilha autenticação interativa por senha.

machine ls

Lista as máquinas cadastradas com o estado da conexão e a versão observada do Herdr Core.

1
hc machine ls

machine login

Refaz a autenticação quando a máquina exige senha ou código. No Windows, ajuste as chaves SSH e use o comando para reconectar.

1
hc machine login <maquina>

machine update

Copia a versão local do Herdr Core para a máquina indicada e reinicia o serviço remoto. A atualização documentada preserva os terminais em execução.

1
hc machine update <maquina>

machine rename

Altera o nome local da máquina. Os endereços que usam o nome antigo deixam de funcionar e precisam ser atualizados nos comandos seguintes.

1
hc machine rename <maquina> <novo-nome>

machine rm

Remove a conexão cadastrada localmente. Os terminais continuam executando na máquina remota.

1
hc machine rm <maquina>

Servidor e atualização

server start

Inicia o Herdr Core para a sessão selecionada. O comando apresenta o estado do servidor após a inicialização.

1
hc server start

server status

Consulta a identificação, o processo e o tempo de atividade do servidor. O comportamento de inicialização varia por plataforma, portanto não use essa consulta como teste universal de ausência de efeitos.

1
hc server status

server stop

Para o servidor. Terminais marcados para recuperação recebem shells novos na próxima inicialização, sem retomar os programas anteriores.

1
hc server stop

server restart

Executa o reinício coordenado do Herdr Core, preservando os programas conforme a documentação da versão 0.1.14. Esse comando não equivale a desligar a máquina ou a executar stop seguido de start.

1
hc server restart

update

Atualiza o binário e reinicia o Herdr Core, preservando os terminais. Sem opções, consulta a release mais recente. --from usa um arquivo local.

1
hc update [--version <X.Y.Z> | --from <arquivo>] [--force]

--version define a versão mínima, sem alterar uma instalação que já esteja nessa versão ou em outra mais recente. --force permite uma versão anterior ou de outra geração do protocolo, embora o estado gravado só avance de formato. Confira a compatibilidade dos clientes ao usar essa opção.

API e integração com clientes

connect

Transporta o protocolo pela entrada e pela saída padrão. --session seleciona a sessão de destino, de forma equivalente à variável HC_SESSION.

1
hc connect [--session <sessao>]

Esse canal atende clientes da API e não abre a interface de um terminal. Também pode ser transportado por SSH.

schema

Imprime a descrição OpenRPC da API com os schemas JSON dos métodos. Use essa saída para consultar os contratos de requisição e resposta da versão instalada.

1
hc schema

Para exemplos de uso com agentes, consulte Herdr Core e a skill do Herdr Core. A referência de Comandos Herdr TUI cobre os workspaces e painéis operados pelo comando herdr.