Command line

Install kowanctl, sign in, and manage Kowan hosts, containers, deployments, workflows, users, API keys and backups from your terminal or scripts.

kowanctl is the command-line client for Kowan. It talks to your Kowan server over the REST API, so it can do whatever your account or API key is allowed to do, from a terminal or a script.

Install

kowanctl needs Python 3.10 or later. Install it with pip:

pip install git+https://github.com/kowan-lab/kowan

Check that it works:

kowanctl version

Sign in

Point kowanctl at your server and sign in with your Kowan username and password:

kowanctl --server https://kowan.example.com login

kowanctl asks for the username and password (or takes them from --username and --password), then saves the server URL and a sign-in token to ~/.kowan/config.yaml. Every later command uses them:

kowanctl hosts ls

A sign-in token is valid for 24 hours. When it expires, run kowanctl login again.

Configuration

kowanctl needs a server URL and a credential: a sign-in token, an API key, or both. It reads each one from a flag, an environment variable or the config file, and uses the first one it finds in this order:

A flag beats an environment variable, which beats the config file, so a variable can override the saved settings for one shell. When both a token and an API key are available, the server authenticates the API key.

The config file is YAML. kowanctl creates it readable only by you (mode 0600), since it holds credentials:

server: https://kowan.example.com
token: eyJhbGciOiJIUzI1NiIs...
apiKey: pk_...

kowanctl login rewrites server and token and keeps an apiKey you added.

Global flags go before the command:

kowanctl --server https://kowan.example.com --api-key pk_... deployment ls

Errors and exit status

On failure, kowanctl prints error: and the reason on standard error and exits with status 1. Errors from the server include the request and the HTTP status, such as error: GET /api/v1/hosts: invalid token (401).

Commands

Each command needs the role of the API call behind it. Viewers can list hosts, containers, images, volumes, networks, deployments and workflows. Operators can also act on containers, deployments and workflows, and see workflow runs. Admins can also rename hosts and manage users, API keys and backups. See Users, roles and teams.

In every group, list also works for ls, and delete for rm.

login

kowanctl --server https://kowan.example.com login [--username NAME] [--password PASSWORD]

hosts

container

Container commands work on one host. --host takes the host's ID, as kowanctl hosts ls shows it, and defaults to local, the server Kowan runs on.

kowanctl container ls --host 3f2c9a1e-... --all
kowanctl container restart 9b1d2c3e4f5a --host 3f2c9a1e-...

image, volume, network

--host defaults to local.

deployment

ID is the deployment ID, as kowanctl deployment ls shows it. See Deployments.

promote prints each change first. --to picks the target (by default, the deployment this one promotes to), --dry-run stops after the list of changes, and --no-deploy saves the target without deploying it.

The file for create holds the deployment as JSON. A container deployment on the local host:

{
  "name": "whoami",
  "type": "container",
  "strategy": "standalone",
  "targets": ["local"],
  "spec": {
    "image": "traefik/whoami:latest",
    "ports": [{ "hostPort": 8080, "containerPort": 80, "protocol": "tcp" }]
  }
}

kowanctl deployment create -f whoami.json
kowanctl deployment deploy 7c0e4b8a-...

For a Compose stack, set "type": "compose" and put the Compose file in "compose" as a string.

workflow

See Workflows and webhooks.

user

apikey

kowanctl apikey create ci-deploy --role operator

Store the secret when it is printed: you cannot see it again. To limit a key to a team or to specific hosts, create it in the console. See API keys.

backup, restore

Both need an admin. See Backup and restore.

mcp

kowanctl mcp [--url URL] [--api-key KEY]

Runs a local MCP server on standard input and output and forwards every message to your Kowan server. It is for AI assistants that start MCP servers as local processes, such as Claude Desktop. See AI assistants.