Command reference
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. |