Korta Enterprise CLI

With a Korta Enterprise manager, korta also manages the platform: instances, SSH keys, databases, applications, roles, operations and an interactive SSH console. Every command goes through the manager, and SSH private keys stay in its vault. The core CLI, which runs roles from your machine without a manager, is described in the CLI reference.

Help follows the command path. Use korta --help for the overview, korta instances --help for instance commands, and korta instances create --help for creation options and examples. The same scoping works for every command group and action; -h is an alias for --help. A bare group such as korta roles also displays that group's help. Help does not connect to a manager or read configuration, inventory, or request files.

Sign in

make build
./bin/korta login --server http://127.0.0.1:8080 --token-file data/admin-token
./bin/korta instances list

Install only the client with go install ./cmd/korta. Without --token-file, korta login asks for the token without echoing it (or reads one line from a pipe). It checks the token, then saves it in korta/config.json in your user configuration directory with mode 0600. korta logout removes the saved token; it does not rotate the manager's admin token.

Setting	Flag	Environment	Default
Manager	--server	KORTA_SERVER	saved server, else http://127.0.0.1:8080
Token	--token-file	KORTA_TOKEN	saved token
Config	--config	KORTA_CONFIG	user config dir /korta/config.json
Deadline	--timeout		10m

Flags win over the environment, which wins over saved credentials. A saved token is only sent to the manager it was saved for. The CLI refuses to send the token over plain HTTP to another machine: use an https:// URL (a TLS proxy in front of korta-server), or pass --insecure on a network you trust. Loopback addresses are always allowed.

Output and exit status

Lists print tables, operations print their steps and results, and other objects print as indented JSON. Use --json (or --output json) in scripts. Errors go to stderr and exit with status 1.

--wait follows an operation until it finishes, printing each step on stderr, and exits 1 if it fails. deployments status, logs and backups, and roles plan, wait by default; add --wait=false to return the operation at once. --timeout limits the whole command including waiting. When it runs out, the operation keeps running on the manager; follow it with korta operations wait op_ID. Consoles are not limited by --timeout.

Instances and SSH keys

korta keys create production --private-key ~/.ssh/id_ed25519
korta keys list
korta instances create db1 --host 10.0.0.5 --user ubuntu --key key_ID --label env=prod --wait
korta instances list
korta instances check ins_ID --wait
korta instances console ins_ID
korta audit --target ins_ID

instances create also takes --port and --host-key 'ssh-ed25519 ...' to pin the host key up front, or the full JSON request with --file. Change an instance with korta instances update ins_ID --file instance.json. After a known reinstall, korta instances trust-host-key ins_ID --wait pins the new host key. For a passphrase-protected key, pass {"name", "privateKey", "passphrase"} with keys create --file FILE.

The console uses the manager's pinned host key and follows terminal resizes. Exit the remote shell to close it. The manager closes idle sessions after 30 minutes and every session after 8 hours.

Databases and applications

korta types
korta deployments create orders-db --type postgres --instance ins_ID --file spec.json --wait
korta deployments list
korta deployments update dep_ID --file spec.json
korta deployments apply dep_ID --wait
korta deployments status dep_ID
korta deployments logs dep_ID --data '{"lines":100}'
korta deployments connection dep_ID --role orders --database orders

With a name and flags, --file holds only the spec, for example:

{
  "roles": [{"name": "orders"}],
  "databases": [{"name": "orders", "owner": "orders"}],
  "access": [{"database": "orders", "role": "orders", "cidr": "10.0.0.0/16"}],
  "backup": {}
}

Without a name, deployments create --file takes the full request (name, type, instanceIDs, spec). The README has the spec for each type. connection prints credentials; capture it only where you mean to store them.

korta deployments restart dep_ID --wait
korta deployments rollback dep_ID --data '{"release":"RELEASE"}' --wait
korta deployments backup dep_ID --data '{"type":"full"}' --wait
korta deployments backups dep_ID
korta deployments restore dep_ID --data '{"confirm":"orders-db","target":"2026-10-30T10:00:00Z"}' --wait

Restore replaces the database's data and needs confirm set to the deployment name, with a backup set, a target time, or both. PostgreSQL backups take a type (full, diff or incr). korta deployments action dep_ID ACTION runs any other action the deployment type offers.

Roles

korta roles preview --markdown role.md
korta roles create --file role.md --name db-access --label env=prod
korta roles plan role_ID
korta roles apply role_ID --approve --wait

preview lists the steps the Markdown compiles to and exits 1 with the line number of the first mistake, so it works as a CI check. create needs --name and targets (--instance ID or --label KEY=VALUE, repeated or comma-separated); --description, --batch-size and --continue-on-failure are optional. korta roles update role_ID --file role.md replaces the Markdown and keeps the name, description, targets and rollout unless you pass new ones. --file also accepts a JSON role object.

plan changes nothing. It shows, for each instance, every step and whether it would change. apply --approve applies the role's current plan, the one you just reviewed, and prints which plan and risks it is approving. Pass --plan op_ID to pin a specific plan. Roles with custom scripts also need --confirm-commands. The manager rejects plans that are stale, older than 24 hours, or already applied.

Secrets

korta secrets set db_password                    # asks for the value, hidden
korta secrets set tls_key --value-file app.key   # from a file
vault read -field=password kv/app | korta secrets set db_password   # from stdin
korta secrets list                               # names and the roles using them
korta secrets delete db_password                 # refused while a role uses it

Secrets live in the manager's vault and roles use them as {{ secret.NAME }}. Values are never taken from arguments, which shells keep in their history, and no command shows them again. Setting an existing name rotates it; plans made before the rotation must be made again. Trailing newlines are removed. Offline, {{ secret.NAME }} reads KORTA_SECRET_NAME from the environment instead.

AI assistant

korta assistant status
korta assistant start --role role_ID
korta assistant send chat_ID --text 'Install nginx on staging hosts'
korta assistant save chat_ID

Saving creates or revises a role; plan and approve it as usual.

Provisioning, activity and the API

korta provision --file provision.json --wait
korta operations list
korta operations wait op_ID --timeout 30m
korta api GET /api/health

korta api METHOD /api/PATH [--data JSON] calls any endpoint, including new ones the CLI has no command for yet. Request bodies must be valid JSON of at most 1 MiB. Server settings such as the listen address and the Anthropic API key are environment variables of korta-server, not API settings.

AWS instance roles

A role that begins with # AWS instance creates its own EC2 instances (see AWS roles). Create it without target flags, then run it:

korta roles create --file web.md --name web
korta roles run role_ID                     # plans, shows the plan, asks to apply
korta roles run role_ID --approve           # the same without the prompt, for CI
korta roles destroy role_ID --confirm web   # plan and approve terminating them

roles run and roles destroy stop after the plan when the manager requires a second approver; that person runs korta roles apply role_ID --approve (with --confirm NAME for a destroy plan). AWS credentials are configured on the manager, never in role files or command arguments.