karactl CLI

karactl manages Karakoram through its REST API, not directly through infrastructure providers.

Install

Follow install karactl for release downloads and checksum verification. Match the CLI release to your server; connecting an older binary does not add commands. From a compatible release checkout with Go 1.26+:

go build -o /tmp/karactl ./cmd/karactl
install -Dm755 /tmp/karactl "$HOME/.local/bin/karactl"

Put $HOME/.local/bin on PATH. make build alternatively produces bin/karactl.

Login and contexts

karactl --server https://example.com --context production login --username admin
karactl --context production health
karactl --context production whoami
karactl config set-context production --namespace production
karactl --context production logout

Login prompts without echo on a terminal; otherwise it reads the first stdin line. Supply noninteractive passwords from a secret manager or protected file, never arguments/history. Complete any mandatory password change in the UI first. Login opens a temporary cookie session, creates an owner-scoped API token, saves the context as current, then closes the session. Re-login saves the replacement before best-effort revocation of the previous token; follow any revocation warning.

config set-context NAME saves explicitly supplied --server, --token and --namespace flags, preserving other saved values. It selects the context only if none is current. Replacing a token this way clears its saved token ID. There is no contexts command; use --context NAME to select one. Outside login, an explicitly selected missing context is rejected.

Contexts are stored at ~/.config/karakoram/config.yaml, independent of XDG overrides, with file mode 0600 and newly created directory mode 0700. Treat this as a credential file.

Selection	Precedence/behavior
Server/token	Explicit flag → KARAKORAM_SERVER / KARAKORAM_TOKEN → saved context
Context	--context → saved current context → default
Object namespace	-n → context namespace → default
Cross-cluster collections	Without explicit -n, include all authorized namespaces, even if the context has a namespace

Server URLs accept the origin or /api/v1 suffix. For automation inject KARAKORAM_SERVER and KARAKORAM_TOKEN securely. Tokens are Karakoram credentials, not provider infrastructure credentials. Logout normally revokes the matching saved token before clearing credentials; logout --local leaves server authority active. With an overriding token, revoke other saved tokens explicitly by ID if necessary.

Requests, output and waits

• -o table is the default; detail output uses sections and list output summarizes nested fields. -o json and -o yaml preserve complete structured responses.
• -f FILE accepts API-shaped YAML/JSON; -f - reads stdin. A supplied file defines the body instead of convenience body flags. Use protected files for secrets. Exceptions: rbac policy set takes raw CSV; engine-native role/key commands use their documented definitions.
• Cluster create files contain {name, spec}. edit replaces the complete {spec} and can open the configured editor without a file. patch, scale and upgrade files contain {spec: {...}} merge patches; arrays replace the previous array, not append to it.
• Complete request files reject explicitly supplied convenience body flags (usage error, exit 2), on every command accepting such a file: creation/source flags, scale resource/replica/topology/component flags, upgrade/FCV version, balancer settings and RBAC permission fields must go in the file rather than silently overriding or being ignored. Put initial cluster provenance in spec.dataSource (cluster, optional namespace, and exactly one of backup or pitrTime); put restore provenance in source/sourceNamespace. Defaults do not override file fields. Execution controls such as namespace/output selection, API query flags, --dry-run and cluster --wait/--timeout remain supported; restores create --file FILE --into-new NAME still clones using the source recorded in the file. Elasticsearch-native role/API-key definition files retain their documented merge/conflict behavior.
• --dry-run previews clusters create, edit, patch, scale, upgrade and restores create on the server using the same request body and namespace, without applying changes. restores create --into-new --dry-run previews creation of the cloned cluster. Table output has changes (paths and compact JSON before → after), effects and warnings; -o json/-o yaml preserves the complete plan. A valid plan exits 0; API validation failures keep the normal error exit status. Dry runs never prompt for destructive confirmation (including -f -) and cannot be combined with --wait.
• Create convenience flags default to psmdb. An omitted/empty --version leaves version selection to the selected engine driver’s catalog. For presets/components, inspect providers get PROVIDER -o json, customize a preset into a complete {name, spec} file, then use clusters create -f FILE. There is no --preset flag. See MongoDB, RabbitMQ and Elasticsearch creation.
• Maintenance convenience flags on cluster spec commands: repeat --maintenance-window 'CRON;DURATION' and select --maintenance-time-zone IANA_NAME (default UTC). --maintenance-window '' clears windows. With -f, put spec: {maintenance: {timeZone: UTC, windows: [{schedule: "0 2 * * 0", duration: 2h}]}} in the file instead; request files remain authoritative.
• --ignore-maintenance-window on restart, rotate-tls, replace-member, members move, raise-fcv, edit, patch, scale, upgrade and upgrade-agents sends the explicit per-operation/per-generation override as an API query parameter. It can accompany -f on commands accepting request files; do not put this control in the request body. It does not bypass quorum or other safety checks. See maintenance semantics and exemptions; clusters get and clusters status include the computed maintenance status.
• PostgreSQL/Supabase creation and current artifact restrictions: PostgreSQL, Supabase. Use full, diff or incr explicitly for their backups; generic logical is not a PostgreSQL type.
• MySQL and PXC are separate engine drivers with a shared mysql access command group. Their backups use full or incremental, and PITR is GTID/binlog based; see MySQL backups.
• Neo4j Community creation, native administrative users and offline outages: Neo4j. Always pass --type dump for Neo4j backups; schedules require engineOptions.acceptBackupDowntime: true.
• Weaviate creation supports single and cluster; use --type full for its backups and its native weaviate users|roles groups for application access.
• clusters connection NAME prints a password-free summary. --reveal explicitly retrieves sensitive engine-admin credentials and CA; do not use that identity for applications or log its output. clusters ca NAME exports only PEM to stdout, regardless of output format, but still requires cluster-credentials:read. Follow MongoDB access, RabbitMQ access or Elasticsearch access.
• Cluster mutation --wait reports acceptance/operation ID on stderr, then phase changes and a fifteen-second heartbeat. The default timeout is 30m. It waits for the operation and observed cluster generation; an Error or Degraded cluster fails the wait. clusters wait NAME observes the current desired generation or deletion/suspension without resubmitting.
• operations wait ID succeeds on Succeeded, even when the cluster is Degraded; Failed/Cancelled fail. Operation success is not a health guarantee. See operations and status.
• Observation retries cover transient connection/timeouts and HTTP 408/429/502/503/504, with bounded backoff and Retry-After handling for 429/503. Invalid URLs, untrusted certificates and nonexistent DNS names fail immediately. Timeout/interruption never cancels server work. Keep the operation ID and use the printed non-mutating resume command.
• Backup/restore creation has no --wait: use the returned operation ID with operations wait, then inspect backups get / restores get. Namespace deletion has no durable Operation or --wait; poll namespaces get and lifecycle events. See namespaces.
• operations cancel ID follows the operation’s persisted namespace, not the selected namespace. It needs cluster-update permission; acceptance can leave Running work in cooperative cleanup and never rolls back desired state. Unsafe/terminal states return 409. See REST API.
• clusters logs returns a bounded log tail: --lines defaults to 100, range 1–10000; --process selects an engine driver-supported child process or agent. Child-process tails come from the authenticated member API. agent reads the member runtime’s provider application logs, including supervisor diagnostics and forwarded child output, not a separate supervised process; availability and retention depend on the provider. --cursor currently has no effect; the server also ignores the API’s since input and returns no next cursor.
• events watch streams until interrupted; see pagination and SSE. openapi downloads raw server YAML without authentication. completion generates scripts without configuration/server access. version always reports client metadata; absent/unreachable server metadata does not itself fail the command, and lookup is limited to five seconds.

karactl has no --idempotency-key flag and does not send Idempotency-Key. For keyed mutation retries use HTTP or the Go client; see safe retries. Do not repeat a mutation merely because waiting or receiving its response failed.

Command groups

This index follows karactl --help; key subcommands are illustrative, not an exhaustive flag reference. All means a shared interface subject to engine driver capabilities and RBAC.

Group/command	Purpose	Key subcommands	Engine applicability
accounts	Local control-plane accounts	list, get, create, set, delete, reset-password, change-password	All
auth	Advanced cookie/OIDC flows	refresh, oidc-login, oidc-callback	All
backends	Registered infrastructure kinds and capabilities	list	All
backups	Backup inventory and creation/deletion	create, list, get, delete, pitr-window	All; pitr-window for engine drivers advertising PITR
backup-drills	Disposable restore verification and reports	list, get, run	All; RabbitMQ definitions only
clusters	Cluster lifecycle/observation	create, list, get, status, members, placement, connection, ca, logs, metrics, edit, patch, scale, upgrade, upgrade-agents, restart, retry-deployments, replace-member, resume, rotate-tls, delete, wait, balancer, raise-fcv	All; balancer/raise-fcv MongoDB only
completion	Generate shell scripts	bash, zsh, fish, powershell	Local
config	Save connection contexts	set-context	Local
control-plane	Coordinator state backups and recovery	backup-policy get/set, backups list/run	Installation-wide
db-roles	Custom database roles	list, get, create, set, delete	MongoDB only
db-users	Database users	list, get, create, set, delete	MongoDB only
elasticsearch	Native access	users, roles, api-keys	Elasticsearch only
events	Durable events/audit and SSE	list, watch	All
health	Control-plane health	—	All
help	Runtime help	any command path	Local
login	Password login and saved API token	—	All
logout	Revoke saved token/remove credentials	—	All
mcp	Stdio MCP bridge; management and per-cluster data MCP client configuration	config, config –cluster NS/NAME	Management: all; data: MongoDB, PostgreSQL, Supabase, Elasticsearch, RabbitMQ
metrics	Prometheus exposition	—	All
mysql	Native database access and PXC quorum recovery	users list/get/create/update/delete/rotate-password/discard-old-password, databases list/get/create/delete, grants list/grant/revoke; recover-quorum	MySQL and PXC; recover-quorum PXC only
namespaces	Project registration/token/relay health	list, get, create, update, validate, rotate-token, delete	All
oauth-grants	Connected OAuth application grants	list, delete	Control-plane accounts; administrators may manage all grants
neo4j	Native administrative users	users list/get/create/delete/password; create/password accept --password-stdin	Neo4j Community only; every user is an admin
notification-channels	Durable operational notifications	list, get, create, replace, delete, test	Installation-wide; settings permissions
openapi	Download server specification	—	All
operations	Observe/cancel asynchronous work	list, cluster, get, wait, cancel	All; cancellation capability varies
orphaned-volumes	Inspect pending platform cleanup	list	All
permissions	Current effective permissions	—	All
postgres	Native database access	roles list/get/create/update/patch/delete/rotate-password, databases list/get/create/delete, grants list/grant/revoke	PostgreSQL and Supabase
providers	Catalogs/defaults/limits	list, get	All
openbao	Initialization material and dynamic-credential connections	unseal-keys reveal; database-connections list/get/create/delete	OpenBao only
rabbitmq	Native access	vhosts, users, permissions, topic-permissions, policies, operator-policies	RabbitMQ only
rbac	Permission checks and policy	can, policy get/set	All
restores	Recovery/clone inventory	create, list, get	All
settings	Control-plane configuration	get, set-oidc, agent-rollout get/set	All
storages	S3 destination registration/probe	list, get, create, set, delete, verify	All
system-users	Engine driver-managed identities	list, rotate	Engine driver-supported identities
supabase	API credentials, SMTP and edge functions	credentials, smtp-password set, functions list/get/deploy/delete, rotate-jwt-secret	Supabase only
temporal	Client certificates, workflow namespaces and write-only UI OIDC secret	client-certificate issue/list, namespace list/delete, ui-oidc-secret set	Temporal only
tokens	Control-plane API tokens	list, get, create, set, delete (alias revoke)	All
version	Client/server build metadata	—	All
weaviate	Native database access	users list/get/create/update/delete/rotate-key; roles list/get/create/update/delete	Weaviate only
whoami	Authenticated identity	—	All

karactl clusters retry-deployments NAME [--namespace NS] [-o json] explicitly re-arms exhausted platform deployments after fixing the underlying platform failure; it requires clusters/update and returns a conflict if no deployment is exhausted.

karactl clusters upgrade-agents NAME [--include-current] [--ignore-maintenance-window] [--wait] [--timeout 30m] rolls out the current agent build without changing engine versions. clusters get shows status.agents target/outdated/unknown details; member output includes agent version/build. Current agents return HTTP 409 AgentsCurrent unless included explicitly. See rolling out member agents.

karactl clusters members move NAME MEMBER [--ignore-maintenance-window] [--wait] [--timeout 30m] requests native member replacement with the current host excluded on placement-capable providers. It asks for confirmation (--yes for automation). Nomad/Dokploy require another eligible node; Zerops is best-effort and provides no host guarantee. Unsupported targets and unknown authoritative placement are refused. Inspect clusters placement NAME and the returned operation; see moving a member.

karactl settings agent-rollout get shows rollout settings and read-only currentBuild. settings agent-rollout set [--automatic=true|false] [--max-concurrent-clusters N] replaces settings (defaults: off and 1; range 1–5). Automatic rollout considers outdated, not unknown/legacy agents.

For engine-native payloads and permissions, use RabbitMQ access, Elasticsearch access and MongoDB. For orphan inventory and manual cleanup, use orphaned platform volumes. PostgreSQL payloads/TLS and proxy compatibility are in PostgreSQL access; Supabase credentials, SMTP and function constraints are in Supabase operations. Neo4j user commands, CA trust and direct Bolt connection caveats are in Neo4j access; the managed neo4j account uses system-users rotate, not native user mutations. PostgreSQL system-users rotate supports enabled Data MCP identities only, not the revealed postgres administrator or other engine-owned accounts. Native role and binding rotations do not rotate that administrator. Read the administrator credential containment limitation before revealing or downloading a PostgreSQL connection credential.

MCP clients

karactl --context production mcp bridges a local stdio MCP client to the control plane’s /mcp using the same server/token resolution as other commands. Standard output contains MCP messages only; diagnostics go to stderr. Tool lists, calls, progress, cancellation, server instructions and human confirmation remain server-controlled. Narrow discovery with --toolsets Clusters,Backups,Workflows; this is not an authorization boundary.

karactl mcp config mints a dedicated restricted token and prints configuration for your client. Without --cluster it configures the management endpoint /mcp; with --cluster NS/NAME it configures that cluster’s data MCP endpoint /mcp/clusters/NS/NAME. Both forms share --client, --write, --token-name and --expires-in (90 days by default; whole days such as 30d or a Go duration such as 720h), and both print the newly minted secret once: protect the output, heed the stderr warning and revoke the token by ID through tokens delete when no longer needed. The server must support restricted API tokens; older servers reject the request.

karactl --context production mcp config --client cursor --namespace production
karactl --context production mcp config --client vscode --expires-in 30d --output /secure/path/mcp.json
karactl --context production mcp config --client codex --stdio
karactl --context production mcp config --cluster production/appdb --client claude-code

Management tokens (no --cluster): clients are claude-code (shell command), cursor, vscode, codex (TOML) or json (generic JSON, default). Tokens are read-only with the name mcp-CLIENT-DATE unless overridden; --write permits mutations only where owner permissions and server mode allow them, and repeatable -n/--namespace restricts the token to namespaces. --stdio prints a karactl mcp command using the selected saved context, with no embedded token, and reveals the newly minted dedicated token once on stderr for separate provisioning; it does not replace the saved context’s token. No files are written unless --output FILE is supplied; this command-specific flag writes configuration with mode 0600, rather than selecting the global output format.

Data tokens (--cluster NS/NAME, always namespace/name, never the implicit namespace): clients are claude-code, cursor, vscode or json; codex is not accepted. The token is scoped to that namespace and cluster with cluster-data:read; --write adds cluster-data:write and removes the read-only restriction, but cluster, owner RBAC and installation write gates still apply. The default name is mcp-data-<cluster>-<hostname>. -n/--namespace, --stdio and --output are usage errors (exit 2) together with --cluster. See MCP security and confirmation and the MCP quick start.

For OAuth-connected applications, use karactl oauth-grants list -o json to inspect visible grants and karactl oauth-grants delete GRANT_ID to revoke a connection. Non-administrators see their own grants; administrators with the required API-token permissions may inspect and revoke all accounts’ grants. Deletion uses the normal destructive confirmation; pass --yes for noninteractive automation. These commands manage account-level grants, not namespace resources.

Use karactl postgres bindings list CLUSTER and karactl postgres bindings rotate CLUSTER ID for managed consumer bindings; neither returns credentials.

Global flags

Flag	Use
--context NAME	Select saved connection
--server URL	Override environment/context server
--token TOKEN	Override API token; prefer environment injection to avoid history/process listings
-n, --namespace NAME	Explicit namespace filter/object scope
-o, --output FORMAT	table (default), json, yaml
--cookie NAME=VALUE	Repeatable advanced-session cookie, not saved
--csrf-token TOKEN	Advanced-session CSRF value, not saved
--insecure-skip-tls-verify	Disable certificate verification; unsafe
-h, --help	Command help

Important command-specific flags

Run karactl <group> <command> --help for every flag. Query flags reach the API only when explicitly supplied; help defaults do not imply resource updates.

Command	Important flags
notification-channels create/replace NAME	create uses --name; --type webhook|slack|email, --enabled, repeatable --category/--namespace, or protected -f JSON/YAML; replace takes positional NAME
notification-channels create/replace destinations	Webhook: --url, --signing-secret-stdin; Slack: --webhook-url-stdin (secret, never an argument); email: --smtp-host, --smtp-port, --security starttls|tls, --username, --password-stdin, --from, repeatable --to
notification-channels test NAME	Prints delivered/error; -o json/-o yaml retain structured result
control-plane backup-policy set	--enabled, --storage [namespace/]name, --schedule (UTC, default 0 3 * * *), --retain-count (1–1000, default 14), -f; replaces policy
control-plane backups list	--limit, --cursor; backups run queues a manual run
clusters create [name]	-f, --provider (psmdb), --version, --backup-storage, repeatable --schedule 'NAME=CRON,type=TYPE,retain=COUNT[,storage=NAME]', --source-namespace, --wait, --timeout
clusters scale NAME	-f, --replicas, CPU/RAM/disk --min-*/--max-*, --start-cpu, --cpu-mode, --wait, --timeout; topology/component flags are engine driver-specific
clusters patch NAME	-f, --wait, --timeout
clusters delete NAME	--keep-volumes, --keep-backups (both false unless supplied), --yes, --wait, --timeout; see delete or suspend
backups create CLUSTER [NAME]	-f, --storage (cluster default), --type (CLI default logical; choose the engine-supported type in backup guidance)
backups list CLUSTER	--limit, --cursor
backup-drills list CLUSTER	--limit, --cursor; table includes ID, phase, backup, trigger, restore duration, data age and creation time
backup-drills get CLUSTER DRILL	Checks, limitations, cleanup and error; --wait, --timeout (6h client default), -o json/yaml
backup-drills run CLUSTER	--backup NAME (otherwise latest successful eligible backup), -f, --wait, --timeout (6h client default); timeout does not cancel server work
clusters create/patch drill policy	--drill-enabled, --drill-schedule (UTC cron), --drill-timeout (server default 6h, range 30m–48h), --drill-backup-schedule; files remain authoritative; see policy shape and scope
restores create CLUSTER [NAME]	-f, --backup, --time (RFC3339, where supported), --source-cluster, --source-namespace, --into-new, --acknowledge-bound-consumers, --yes
namespaces create	--name, --project-id (provider target ID), --token-file, --description, --backend (zerops), repeatable --config key=value (non-secret provider settings; Zerops accepts none, its API URL is operator-only); no -f
storages create/set	-f; verify NAME checks connectivity separately; list has --limit, --cursor; delete has --yes
tokens create	-f OR --name, --expires (RFC3339 or duration), --read-only, repeatable --scope-namespace, --scope-cluster ns/name, --permission resource:action, --allow-credential-reveal
tokens set	-f (name/expiry only); list has --limit, --cursor; delete/revoke has --yes
mcp config	--client claude-code|cursor|vscode|codex|json (json), --write, --token-name, --expires-in (90d; whole days or Go duration); management only: repeatable -n/--namespace, --stdio, --output FILE; data: --cluster NS/NAME (no codex; rejects -n, --stdio, --output)
events list	--cluster, --type, --operation, --actor, --resource, --order asc|desc, --limit, --cursor
events watch	Same scope filters; --cursor, --last-event-id; no list limit/order
operations list/cluster	--phase, --limit, --cursor; list also --cluster
operations wait/cancel ID	wait: --timeout (30m); cancel: --yes

Weaviate native access

Use karactl weaviate users create CLUSTER NAME --role viewer, users update CLUSTER NAME --role viewer --active (or --inactive), and users rotate-key CLUSTER NAME --yes. --role is repeatable; update replaces the complete role list, and omission clears roles. User list/get/delete and role list/get/delete take the cluster and, for object actions, the name. Role create uses roles create CLUSTER -f role.yaml; replacement uses roles update CLUSTER NAME -f role.yaml, with {name, permissions}.

Generated user API keys are secret-bearing creation/rotation results, not later GET data; protect terminal output. Do not blindly retry after losing a mutation response: the CLI does not send idempotency keys. Protected identities and extra privilege grants follow the Weaviate access guide; MongoDB db-users/db-roles do not apply.

Key rotation requires database-users/update plus clusters/update when the target user’s current roles include anything beyond viewer or read-only. User deletion needs only database-users/delete, including for privileged users; protected identities remain excluded.

Supabase native access

karactl supabase credentials CLUSTER masks API keys, the dashboard password and JWT secret in every output format. Pass --show-secrets only when sensitive terminal or redirected output is protected. The endpoint requires the separate cluster-credentials:read grant and returns Cache-Control: no-store.

karactl supabase smtp-password set CLUSTER reads the password through a hidden terminal prompt or the first stdin line; passwords are never accepted as command arguments. For example, pipe a secret manager’s output directly into this command.

Use karactl supabase functions list CLUSTER, functions get CLUSTER NAME, functions deploy CLUSTER NAME DIR_OR_FILE, and functions delete CLUSTER NAME. Deploy sends a map of relative file paths to source text; directories are recursive and require a nonempty index.ts entrypoint. A standalone source file is deployed as index.ts. Symlinks and special files are rejected, and source text is limited to 1 MiB per function. A cluster supports at most 100 functions. Names match [a-z0-9][a-z0-9_-]{0,62}; main is reserved for the runtime dispatcher, and parent traversal is forbidden. Sources are stored sealed but remain readable to callers with cluster-read permission, so do not embed application secrets in source files.

Function deletion and karactl supabase rotate-jwt-secret CLUSTER require confirmation (or --yes). Rotation queues a durable rotate-jwt-secret operation; track the returned ID with karactl operations get or operations wait. SMTP and function mutations require cluster-update permission; audit events contain identifiers, never passwords or source text.

MySQL native access

The mysql command group administers application accounts and database-level grants:

karactl mysql users list CLUSTER
karactl mysql users get CLUSTER USER
karactl mysql users create CLUSTER -f user.json
karactl mysql users update CLUSTER USER -f user.json
karactl mysql users rotate-password CLUSTER USER --retain-current
karactl mysql users discard-old-password CLUSTER USER
karactl mysql databases list CLUSTER
karactl mysql databases get CLUSTER DATABASE
karactl mysql databases create CLUSTER -f database.json --character-set utf8mb4 --collation utf8mb4_0900_ai_ci
karactl mysql grants list CLUSTER --user USER
karactl mysql grants list CLUSTER --database DATABASE
karactl mysql grants grant CLUSTER -f grant.json
karactl mysql grants revoke CLUSTER -f grant.json --yes
karactl mysql databases delete CLUSTER DATABASE --force --yes
karactl mysql users delete CLUSTER USER --yes

Accounts use the fixed 'name'@'%' identity and require TLS. Creation and password rotation return a server-generated generatedPassword once, using the same JSON/YAML/table output conventions as PostgreSQL role creation; save it securely and never log the response. --retain-current keeps the previous password valid during a credential rollout; discard-old-password removes that retained password.

User creation documents contain name and optional locked and maxUserConnections. users update sends a partial attribute update: omitted fields stay unchanged, and only locked and maxUserConnections may be changed. Passwords are managed separately through rotation, not supplied in user documents.

Database documents contain name and optional characterSet and collation. The creation flags override the corresponding document fields; these properties cannot be updated after creation. Database deletion refuses nonempty databases unless --force is supplied. Grant documents contain user, database and privileges; grants are database-level only, not global or administrative privileges. Listing grants requires a nonempty --user or --database filter (both may be supplied). User deletion, database deletion and privilege revocation require confirmation or --yes.

PostgreSQL native access

The postgres command group also works with Supabase clusters, which share the PostgreSQL core:

karactl postgres roles list CLUSTER
karactl postgres roles get CLUSTER ROLE
karactl postgres roles create CLUSTER -f role.json
karactl postgres roles update CLUSTER ROLE -f role.json
karactl postgres roles rotate-password CLUSTER ROLE --yes
karactl postgres databases create CLUSTER -f database.json
karactl postgres databases list CLUSTER
karactl postgres databases get CLUSTER DATABASE
karactl postgres grants list CLUSTER --database DATABASE
karactl postgres grants grant CLUSTER -f grant.json
karactl postgres grants revoke CLUSTER -f grant.json --yes
karactl postgres databases delete CLUSTER DATABASE --force --yes
karactl postgres roles delete CLUSTER ROLE --yes

A role document contains name, login (default true), createdb, createrole, connectionLimit (default -1), memberOf, optional RFC3339 validUntil, and optional password. Omitted passwords on login-role creation are generated and returned once as generatedPassword; rotation returns a new generated password. Responses are no-store; an identical request with the same idempotency key safely replays its sealed result. Never put passwords in command arguments or commit credential-bearing request documents. Privileged superuser, replication, and bypassrls flags, privileged memberships, and changes to existing privileged role passwords additionally require cluster-update permission. Engine system roles are hidden and immutable; Supabase service roles are protected too.

A database document contains name, owner, optional encoding (UTF8), locale (C.UTF-8), and allowConnections (true). Encoding and locale cannot be changed after creation. A grant document contains role, database, privileges, and optional schema: database privileges are CONNECT/CREATE/TEMP; schema privileges are USAGE/CREATE. Predefined memberships include pg_read_all_data, pg_write_all_data, pg_monitor, pg_read_all_stats, and pg_signal_backend.

Managed login passwords are sealed and synchronized to every ProxySQL member without restarting PostgreSQL. Roles created directly in SQL are not routable through ProxySQL. Use the proxy hostname, cluster CA, and sslmode=verify-full for TLS connections; public endpoints are advertised when enabled and configured by the infrastructure provider. Direct data-member endpoints remain private. Role/database deletion, grant revocation, and password rotation require confirmation (or --yes).

Access operations use authenticated internal POST actions on a freshly resolved primary. HA members also require the Patroni leader lock; no writable primary produces HTTP 503. Only a precomputed SCRAM-SHA-256 verifier crosses the role-action protocol, never the plaintext password in SQL. Membership replacement is transactional; schema grants connect to the requested database. roles patch CLUSTER ROLE -f patch.json changes only supplied fields; roles update replaces role attributes.

ProxySQL does not implement every PostgreSQL protocol feature. In particular, clients requesting different result formats per column must select a uniform format (for pgx, use simple protocol or request text results). Supabase’s internal services bypass ProxySQL for features such as LISTEN/NOTIFY and logical replication.

Restricted API tokens

karactl tokens create --name inventory --expires 720h --read-only \
  --scope-namespace prod --permission clusters:read

Without -f, creation requires --name; combining a request file with any token creation flag is a usage error (exit 2). Repeat scope/permission flags to add entries. --scope-namespace restricts the new token; persistent --namespace/-n remains the request’s REST scope. --expires accepts an RFC3339 timestamp or a positive Go duration relative to creation.

Omitting all restriction flags creates an unrestricted token. Supplying any restriction flag creates an immutable deny overlay; credential reveal defaults to disabled, including on otherwise read-only tokens. List/get/create table output summarizes restrictions; JSON/YAML retain the full fields. karactl login creates an unrestricted token. See restricted API tokens for scope, permission, issuance and OIDC rules. Distributed PostgreSQL adds karactl postgres rebalance CLUSTER [--strategy NAME] [--wait] (PostgreSQL only, not Supabase). --wait follows the returned operation; timeout does not cancel it. Worker groups scale through clusters patch using spec.engineOptions.citus.workerGroups. See distributed PostgreSQL for artifact availability, coordinated recovery and limits.

Temporal native access

karactl temporal client-certificate issue CLUSTER --common-name worker --ttl 720h --out-dir DIR
karactl temporal client-certificate list CLUSTER
karactl temporal namespace list CLUSTER
karactl temporal namespace delete CLUSTER NAME --yes
karactl temporal ui-oidc-secret set CLUSTER --from-file FILE

Certificate issuance requires exactly one of --out-dir DIR or --stdout; stdout contains the private key, so protect redirected output. Existing files are not overwritten. Secret input requires exactly one of --from-file FILE or --from-stdin; there is no argv secret flag. All commands accept -n NS for the Karakoram namespace, not the workflow namespace. See Temporal access/TLS for permissions, output modes, SDK configuration and operations for destructive namespace deletion.

Safety and exit statuses

Deletion, in-place restores, member replacement, compatibility-version raises, credential/TLS/namespace-token rotation, account password resets and operation cancellation prompt Type the name to confirm when stdin is a terminal. Compound identities use the final argument; in-place restore asks for the target cluster. --yes/-y skips confirmation and is required when stdin carries a request body. Without a terminal, one line containing y or yes (case-insensitive) confirms; another nonempty answer cancels (1), and empty input/EOF is a usage error (2), without mutation.

Repeated cluster deletion with unchanged retention options returns the same in-flight Operation; changing either option supersedes its tracking record. storages verify fails even after HTTP success when verified: false. Errors include available field/reason/resource context on stderr.

Exit	Meaning
0	Success
1	Generic failure, failed/cancelled operation, declined confirmation, failed storage verification
2	Usage/argument/flag error or missing noninteractive confirmation
3	HTTP 404
4	HTTP 409
5	HTTP 401/403
6	HTTP 400/415/422 validation/media error
7	Wait deadline or HTTP 408/504; accepted work may continue

OpenBao access and recovery

karactl -n NS openbao unseal-keys reveal secrets --confirm secrets -o json
karactl -n NS openbao database-connections create secrets \
  --name orders --target ordersdb --role reader:readonly \
  --default-ttl 1h --max-ttl 24h
karactl -n NS openbao database-connections list secrets -o json
karactl -n NS openbao database-connections get secrets orders -o json
karactl -n NS openbao database-connections delete secrets orders --yes
karactl -n NS backups create secrets beforechange --type raft-snapshot --storage archive

Reveal prints real shares and the initial root token in every output format; protect stdout and offline custody. It requires the distinct openbao-unseal-keys:reveal grant and exact --confirm. Connection creation accepts -f or --name, --target and repeatable --role name:readonly|readwrite[:database]; TTL flags require positive whole seconds and fill roles without explicit TTLs. RabbitMQ roles in one connection must share the same TTL pair. The returned paths are read through OpenBao with native tokens, not through karactl. Shared restart/replace-member/rotate-tls commands manage lifecycle; only catalog-listed forward versions are allowed. Use protected request files for write-only openbaoUnsealShares on deleted-source restores/clones. See OpenBao access, operations and snapshots.