Command line

KubeGlass takes almost all of its configuration from KUBEGLASS_* environment variables or a kubeglass.yaml file (see Configuration). The command line has only a few flags.

kubeglass

Starts the server and opens it in your browser.

kubeglass [KIND[/NAME]] [--context NAME] [-n NAMESPACE] [--kubeconfig FILE]
          [--port N] [--base-path PATH] [--no-browser] [--read-only] [--local-shell] [--verbose] [--demo]
          [--version] [--healthcheck]

Flag	Does
KIND	Open that kind’s list instead of the Overview, by any name : takes in the command palette: pods, deploy, svc, certificates.cert-manager.io
KIND/NAME	Open one object: po/web-1 -n shop, node/worker-1. Without -n, a namespaced object is looked for in every namespace
--context NAME	Open this kubeconfig context. KubeGlass checks that it exists and exits with the list of contexts when it doesn’t
-n NAME, --namespace NAME	Open this namespace
--kubeconfig FILE	Read this kubeconfig instead of $KUBECONFIG or ~/.kube/config, as kubectl --kubeconfig does
--port N	Listen on port N. Same as KUBEGLASS_PORT
--base-path PATH	Serve KubeGlass under PATH, such as /kubeglass, for an ingress or proxy that routes that path to it. Same as KUBEGLASS_BASE_PATH; see Serving under a path
--no-browser	Don’t open a browser tab. Same as KUBEGLASS_NO_BROWSER=1
--verbose	Print the full server log to the terminal instead of a log file
--read-only	Refuse every change, whatever RBAC allows: no edits, deletes, scaling, restarts, shells or port forwarding. Same as KUBEGLASS_READ_ONLY=true
--local-shell	Offer a shell on this computer in the dock, set to the cluster you have open. Only in local auth mode, outside a cluster and without --read-only. Same as KUBEGLASS_ENABLE_LOCAL_SHELL=true; see Terminal
--demo	Run with built-in sample data. No cluster is needed and nothing is changed. Same as KUBEGLASS_DEMO_MODE=true
--version, version	Print the version, commit and build date, then exit
--healthcheck	Call the local server’s /healthz and exit with 0 when it answers. It asks the port --port or KUBEGLASS_PORT gives, else the one the server recorded in its data directory, else kubeglass.yaml’s, and over TLS it trusts the configured certificate (tls_cert) whatever names it has. A kubeglass.yaml that no longer validates doesn’t fail it while the server answers at the recorded address. The container image uses this as its health check
-h, --help, help	Show usage

Flags can come before or after the kind, as in k9s:

kubeglass deploy -n shop               # Deployments in shop
kubeglass --context prod pods          # Pods on the prod cluster
kubeglass po/api-7d9f -n shop          # one pod's page
kubeglass --kubeconfig ./kind.yaml     # a kubeconfig other than your own

At a terminal, KubeGlass prints its address and your clusters, then opens the address in your default browser. The full log goes to kubeglass.log in the data directory (~/.kubeglass/data by default), the demo’s to kubeglass-demo.log; the previous run’s log is kept as kubeglass.log.1. Errors are still printed to the terminal. When the output is not a terminal, as in a container, the log goes to stdout as JSON.

The browser is not opened over SSH, inside a cluster or a CI job, on Linux without a display, or when BROWSER=none.

The default port is 8090. If another program has it, KubeGlass takes the next free port up to 8100 and prints the one it chose. A port you set with --port or KUBEGLASS_PORT is never changed: KubeGlass exits if it is taken. If KubeGlass itself is already running on the port, a second kubeglass opens the running one and exits; kubeglass --demo does so only for a running demo, and beside a KubeGlass on a cluster takes the next free port, as a KubeGlass on a cluster does beside a demo. A second one on another port needs a data directory of its own (KUBEGLASS_DATA_DIR): with the same one, it waits up to 5 seconds for it, as a KubeGlass that just stopped can still hold it, then says which KubeGlass uses it and exits. --demo keeps nothing there and starts beside it. With a kind, --context or -n, it opens that page there, so kubeglass deploy -n shop works whether or not KubeGlass is running. The running KubeGlass keeps the kubeconfig it started with, so --kubeconfig only takes effect when KubeGlass starts.

If the kubeconfig has no current-context, or it names a context that doesn’t exist, KubeGlass starts on the first context in alphabetical order. Your kubeconfig is not changed.

If no kubeconfig can be loaded, KubeGlass starts in setup mode instead of exiting: the UI offers to start a local cluster, paste a kubeconfig, or open the demo, and continues as soon as a kubeconfig appears.

kubeglass mcp

Runs the MCP server over stdio. KubeGlass itself must already be running.

kubeglass mcp [--url URL] [--token TOKEN]

Flag	Environment	Default	Does
--url	KUBEGLASS_URL	The KubeGlass running on this machine, or http://localhost:8090	The KubeGlass to query
--token	KUBEGLASS_TOKEN	empty	Bearer token, for a KubeGlass in oidc mode (a JWT from the provider) or token mode (a Kubernetes token)

Exit codes

Code	Meaning
0	Clean shutdown, or --version, --help and a passing --healthcheck
1	The server or the MCP server failed, --healthcheck got no answer, or kubeglass mcp got an unknown flag
2	kubeglass got an unknown flag, more than one kind, a kind or name it can’t read, a --kubeconfig file that doesn’t exist, or a --context the kubeconfig doesn’t have