Referência de comandos
Todos os comandos são escritos konsolity <command> [options]. konsolity help e konsolity <command> --help exibem a ajuda no idioma do sistema. As saídas em --json são estáveis e feitas para scripts; elas nunca contêm segredos.
Visão geral
| Comando | Domínio necessário | Função |
|---|---|---|
login |
Ativar a máquina (Ativar uma máquina) | |
setup-token |
Criar um token de longa duração para CI e contêineres | |
status |
Conta, máquina, escopo, expiração, estado | |
hosts |
hosts |
Hosts do escopo |
run |
hosts, acesso completo |
Executar um comando num host |
snippet list |
snippets |
Snippets do escopo |
snippet run |
snippets + hosts, acesso completo |
Executar um snippet num host |
sessions |
sessions |
Sessões CLI em andamento na conta |
sessions end |
sessions |
Encerrar uma sessão |
mcp |
mcp |
Servidor MCP local para o Claude Code (MCP local) |
serve |
mcp + integração Claude |
Tratar as solicitações do conector Claude (Serviço) |
service install |
Instalar o serve como serviço do sistema |
|
rotate |
Renovar o token da máquina | |
policy |
Exibir o escopo e as regras aplicadas | |
logout |
Revogar a máquina e apagar tudo localmente | |
version |
Versão, sistema, arquitetura | |
update |
Atualizar o binário (assinatura verificada) |
Um comando fora do escopo responde scope_denied; um comando numa máquina somente leitura responde read_only.
login
konsolity login [--name <name>] [--scopes hosts,snippets,sessions,mcp] [--read-only]
Ativa a máquina com um código aprovado a partir da sua conta. Detalhes e exemplos: Ativar uma máquina.
setup-token
konsolity setup-token [--name <name>] [--scopes <list>] [--read-only]
Mesmo fluxo que o login, mas exibe uma única vez um token ksetup_... em vez de gravar qualquer coisa. Depois, forneça-o por KONSOLITY_TOKEN. Consulte setup-token.
status
konsolity status [--json]
Exibe a conta, o nome e o tipo da máquina, o escopo (domínios, somente leitura ou completo), a expiração, a idade do token, o estado do servidor e o número de hosts acessíveis.
$ konsolity status
Account anthony@example.com
Machine build-01 (machine)
Scope hosts, snippets, mcp · full access
Expires on 2027-02-08
Token renewed 3 h ago
Server api.konsolity.com · reachable
Hosts 4
hosts
konsolity hosts [--json]
Lista os hosts do escopo: rótulo, endereço, usuário, grupo. Nunca uma senha ou uma chave.
$ konsolity hosts
web-01 203.0.113.10 deploy Production
web-02 203.0.113.11 deploy Production
db-01 10.0.0.5 admin Data
run
konsolity run <host> [--timeout <seconds>] [--json] -- <command>
Executa um comando num host por SSH: conexão curta dedicada, chave de host fixada obrigatória, saída ao vivo no terminal, código de retorno do comando remoto repassado como código de saída do konsolity. <host> é o rótulo do host ou o seu identificador. Tudo o que vem depois de -- é o comando, tal como está.
| Opção | Função |
|---|---|
--timeout <seconds> |
Tempo limite do comando, limitado pelo tempo limite máximo da máquina (60 s por padrão). |
--json |
Uma única saída JSON no final: exit_code, stdout, stderr, duration_ms. |
$ konsolity run web-01 -- systemctl status nginx
● nginx.service - A high performance web server
Active: active (running) since Mon 2026-11-09 08:12:44 UTC
$ echo $?
0
Antes de executar o comando, a CLI verifica o escopo e as regras e depois registra o início no registro: se essa gravação falhar, o comando não é executado. Um comando destrutivo aguarda a sua confirmação:
$ konsolity run db-01 -- "mysql -e 'DROP TABLE sessions_old'"
Destructive command: confirmation requested in the Konsolity app.
https://app.konsolity.com/cli/confirm/9f3c2a71
Waiting (5 min at most)...
Allowed. Running.
snippet
konsolity snippet list [--json]
konsolity snippet run <snippet> <host> [--timeout <seconds>] [--json]
snippet list exibe os snippets do escopo (nome, grupo). snippet run executa um snippet, tal como está salvo no cofre, num host do escopo. <snippet> é o nome ou o identificador dele. Valem as mesmas regras do run: registro, confirmação se o conteúdo for destrutivo, código de retorno repassado.
$ konsolity snippet run "Clear the cache" web-01
Cache cleared.
sessions
konsolity sessions [--follow] [--json]
konsolity sessions end <id>
Lista as sessões CLI em andamento na conta: máquina, comando, desde quando. --follow mantém a lista aberta e a atualiza. sessions end <id> encerra uma sessão: o comando correspondente é interrompido em menos de 5 segundos.
$ konsolity sessions
a1b2c3 build-01 run web-01: tail -f /var/log/nginx/access.log for 12 min
d4e5f6 laptop mcp for 1 h
$ konsolity sessions end a1b2c3
mcp
konsolity mcp
Inicia um servidor MCP stdio local, para conectar no Claude Code:
claude mcp add konsolity -- konsolity mcp
Detalhes das ferramentas e dos limites: MCP local para o Claude Code.
serve
konsolity serve
Trata as solicitações do conector Claude da conta (claude.ai, app Claude) como faz o app de computador, mas sem interface, dentro dos limites do escopo e das regras. Exige o domínio mcp e a integração Claude do plano Studio. Fica em primeiro plano; num servidor, instale-o como serviço.
service install
sudo konsolity service install
Instala o konsolity serve como serviço do sistema (systemd, launchd ou tarefa agendada do Windows). Consulte Serviço e armazenamento.
rotate
konsolity rotate
Força a renovação do token da máquina. De qualquer forma, a rotação é automática a cada 24 horas. A chave de máquina não muda.
policy
konsolity policy [--json]
Exibe o que a máquina aplica de fato: domínios, somente leitura ou completo, hosts, snippets, regras de comando, “Qualquer comando”, tempo limite máximo.
logout
konsolity logout
Revoga a máquina no servidor e depois apaga o token, a chave de máquina e as cópias locais. Para usar a máquina de novo, é preciso uma nova ativação.
version
konsolity version
Exibe a versão, o sistema e a arquitetura.
update
konsolity update
Baixa a versão mais recente, verifica o hash SHA-256 dela e a assinatura Ed25519 do manifesto e depois substitui o binário. Se tiver sido instalada pelo apt, pelo dnf ou pelo Homebrew, a CLI indica esse gerenciador.
Variáveis de ambiente
| Variável | Função |
|---|---|
KONSOLITY_TOKEN |
Token de longa duração ksetup_... (CI, contêineres). Substitui os segredos gravados. |
Códigos de saída
| Código | Significado |
|---|---|
0 |
Sucesso. |
| código remoto | run e snippet run saem com o código de retorno do comando remoto (por exemplo 1 se o comando falhou no host). |
1 |
Erro geral: máquina não ativada, rede inacessível, host ou snippet não encontrado, linha de registro não gravada (o comando então não é iniciado), segredos locais ilegíveis. |
2 |
Erro de uso: opção desconhecida, comando ausente ou longo demais (4.000 caracteres no máximo), KONSOLITY_TOKEN inválido. |
3 |
Recusa: domínio ausente do escopo (scope_denied), máquina somente leitura (read_only), nenhuma regra corresponde (denied), regras ausentes (policy_missing), plano exigido (plan_required) ou ativação recusada. |
4 |
Comando destrutivo não confirmado: recusado no app ou no console, ou sem resposta em 5 minutos. Ele não foi iniciado. |
77 |
Máquina revogada, expirada ou usada a partir de outro computador (impressão digital diferente), ou sessão encerrada a partir do app ou do console: as conexões são cortadas e o comando é interrompido. Exceto num simples encerramento de sessão, os segredos locais também são apagados. |