Command reference

Updated on November 10, 2026

Every command is written konsolity <command> [options]. konsolity help and konsolity <command> --help show the help in the language of the system. --json outputs are stable and meant for scripts; they never contain a secret.

Overview

Command Required domain Role
login Activate the machine (Activate a machine)
setup-token Create a long-lived token for CI and containers
status Account, machine, scope, expiry, status
hosts hosts Hosts in the scope
run hosts, full access Run a command on a host
snippet list snippets Snippets in the scope
snippet run snippets + hosts, full access Run a snippet on a host
sessions sessions CLI sessions running on the account
sessions end sessions End a session
mcp mcp Local MCP server for Claude Code (Local MCP)
serve mcp + Claude integration Handle the requests of the Claude connector (Service)
service install Install serve as a system service
rotate Renew the token of the machine
policy Show the scope and rules applied
logout Revoke the machine and erase everything locally
version Version, system, architecture
update Update the binary (signature checked)

A command outside the scope answers scope_denied; a command on a read-only machine answers read_only.

login

konsolity login [--name <name>] [--scopes hosts,snippets,sessions,mcp] [--read-only]

Activates the machine with a code approved from your account. Details and examples: Activate a machine.

setup-token

konsolity setup-token [--name <name>] [--scopes <list>] [--read-only]

Same flow as login, but shows once a ksetup_... token instead of saving anything. Then provide it through KONSOLITY_TOKEN. See setup-token.

status

konsolity status [--json]

Shows the account, the name and type of the machine, the scope (domains, read-only or full), the expiry, the age of the token, the server status and the number of reachable hosts.

$ 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]

Lists the hosts in the scope: label, address, user, group. Never a password or a key.

$ 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>

Runs a command on a host over SSH: short dedicated connection, pinned host key required, live output in the terminal, exit code of the remote command passed on as the exit code of konsolity. <host> is the label of the host or its identifier. Everything after -- is the command, as is.

Option Role
--timeout <seconds> Timeout of the command, capped by the maximum timeout of the machine (60 s by default).
--json A single JSON output at the end: 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

Before running the command, the CLI checks the scope and the rules, then writes the start to the log: if that write fails, the command is not run. A destructive command waits for your confirmation:

$ 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 shows the snippets in the scope (name, group). snippet run runs a snippet, as it is saved in the vault, on a host in the scope. <snippet> is its name or its identifier. The same rules as run apply: log, confirmation if the content is destructive, exit code passed on.

$ konsolity snippet run "Clear the cache" web-01
Cache cleared.

sessions

konsolity sessions [--follow] [--json]
konsolity sessions end <id>

Lists the CLI sessions running on the account: machine, command, since when. --follow keeps the list open and refreshes it. sessions end <id> ends a session: the matching command is stopped in less than 5 seconds.

$ 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

Starts a local stdio MCP server, to connect in Claude Code:

claude mcp add konsolity -- konsolity mcp

Details of the tools and limits: Local MCP for Claude Code.

serve

konsolity serve

Handles the requests of the account's Claude connector (claude.ai, Claude app) like the desktop app does, but without an interface, within the scope and rules. Requires the mcp domain and the Claude integration of the Studio plan. Stays in the foreground; for a server, install it as a service.

service install

sudo konsolity service install

Installs konsolity serve as a system service (systemd, launchd or a Windows scheduled task). See Service and storage.

rotate

konsolity rotate

Forces the renewal of the machine token. Rotation is automatic every 24 hours anyway. The machine key does not change.

policy

konsolity policy [--json]

Shows what the machine actually applies: domains, read-only or full, hosts, snippets, command rules, "Any command", maximum timeout.

logout

konsolity logout

Revokes the machine on the server, then erases the token, the machine key and the local copies. To use the machine again, a new activation is needed.

version

konsolity version

Shows the version, the system and the architecture.

update

konsolity update

Downloads the latest version, checks its SHA-256 hash and the Ed25519 signature of the manifest, then replaces the binary. When installed with apt, dnf or Homebrew, the CLI points you to that manager.

Environment variables

Variable Role
KONSOLITY_TOKEN Long-lived ksetup_... token (CI, containers). Takes the place of the saved secrets.

Exit codes

Code Meaning
0 Success.
remote code run and snippet run exit with the exit code of the remote command (for example 1 if the command failed on the host).
1 General error: machine not activated, network unreachable, host or snippet not found, log line not written (the command is then not started), local secrets unreadable.
2 Usage error: unknown option, missing or too long command (4,000 characters at most), invalid KONSOLITY_TOKEN.
3 Refused: domain missing from the scope (scope_denied), read-only machine (read_only), no rule matches (denied), rules missing (policy_missing), plan required (plan_required) or activation denied.
4 Destructive command not confirmed: denied in the app or the console, or no answer within 5 minutes. It was not started.
77 Machine revoked, expired or used from another computer (different fingerprint), or session ended from the app or the console: connections are cut and the command stopped. Except for a plain end of session, local secrets are erased too.