Referência de comandos

Atualizado em 10 de novembro de 2026

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.