CLI

CLI Command Reference

Every kubeadapt command and flag: organization, clusters, namespaces, workloads, pods, nodes, node groups, recommendations, teams, departments, auth.

Last updated 2026-10-29

All commands support the global flags (--output, --api-key, --verbose, and others). List commands also accept the pagination flags.

Quick reference

Command	Description
`get overview`	Organization summary: capacity, usage, counts, hourly cost
`get dashboard`	Organization dashboard with month-to-date cost and savings
`get clusters`	List clusters
`get cluster <id>`	Show a single cluster
`get namespaces`	List namespaces
`get namespace <name>`	Show a single namespace
`get workloads`	List workloads
`get workload <uid>`	Show a single workload
`get pods <workload-uid>`	List pods for a workload
`get nodes`	List nodes
`get node <uid>`	Show a single node
`get node-groups`	List node groups
`get node-group <name>`	Show a single node group
`get recommendations`	List recommendations
`get recommendation <id>`	Show a single recommendation
`get teams`	List teams with cost attribution
`get team <id>`	Show a single team
`get team-assignments <id>`	List assignments for a team
`get departments`	List departments with cost attribution
`get department <id>`	Show a single department
`health`	Check API server health (unauthenticated)
`auth login`	Verify and store an API key
`auth status`	Verify the active API key and show the masked key, API URL, and organization
`auth logout`	Remove the stored API key
`version`	Binary version, commit, build date, Go version, OS/arch
`completion`	Shell completion scripts

Pagination flags

List commands accept these flags. get node-groups returns every group in one response and rejects --limit, --cursor, --paginate, and --include-total.

Flag	Type	Default	Description
`--cost-mode`	string	`fully_loaded`	Cost attribution mode (`fully_loaded` or `workload_only`). Applies to namespace, workload, pod, team, department, and dashboard commands.
`--cursor`	string	—	Pagination cursor from a previous response.
`--limit`	int	`100`	Page size (1–500).
`--paginate`	bool	`false`	Fetch every page. Each row appears once even while costs change during the walk, and the rows are printed in the usual order.
`--include-total`	bool	`false`	Include `total_count` in pagination metadata. Slower.
`--max-wait`	duration	`15m0s`	With `--paginate`, the longest total time spent waiting out API rate limits before returning partial results (`0` = unbounded).

Commands whose endpoint has no cost mode (clusters, cluster, nodes, node, node-groups, node-group, recommendations, recommendation, team-assignments, overview) reject --cost-mode and exit 2.

Flags that take a fixed set of values (--status, --phase, --entity-type and the others listed below) are checked before any request is sent. A value outside the set exits 2 and lists the accepted values. Shell completion offers the same values.

When more results exist, the table footer prints the cursor for the next page, and JSON output carries it in meta.pagination.next_cursor. If a --paginate run stops early (for example, the --max-wait budget runs out), the CLI prints what it fetched, exits 1, and writes a resume cursor to stderr. Tables add a PARTIAL RESULTS line with the cursor; JSON and YAML add partial: true and resume_cursor.

If the API ignores a filter it does not recognize, the CLI prints a warning to stderr, because the results are not filtered by it.

get overview

Shows the organization summary: CPU, memory, GPU, and storage capacity and usage, counts of clusters, nodes, namespaces, workloads, pods, and recommendations, and the current hourly run rate.

bash

kubeadapt get overview

No additional flags.

get dashboard

Shows the organization dashboard: month-to-date spend, the current hourly run rate, recommendation count and hourly savings potential, and the top clusters with their hourly and month-to-date cost.

Flag	Type	Default	Description
`--top-clusters-limit`	int	`0` (server default, currently 5)	Number of top clusters to include (0–20)
`--cost-mode`	string	`fully_loaded`	`fully_loaded` or `workload_only`

Example

bash

kubeadapt get dashboard --top-clusters-limit 10

get clusters

Lists all clusters in your organization.

Flag	Type	Default	Description
`--provider`	string	—	`aws`, `gcp`, `azure`, or `on-prem`
`--region`	string	—	Region, e.g. `us-east-1`
`--environment`	string	—	`production`, `non-production`, `staging`, or `dev`
`--status`	string	—	`pending`, `active`, `disconnected`, `error`, or `discovered`

Example

bash

kubeadapt get clusters --provider aws --region eu-west-1

get cluster

Shows details for a single cluster. Requires the cluster ID as a positional argument.

Arguments

Argument	Required	Description
`cluster-id`	yes	The cluster ID to look up

Example

bash

kubeadapt get cluster c1a2b3c4-d5e6-7890-abcd-ef1234567890

get workloads

Lists workloads across your clusters.

Flags

Flag	Type	Default	Description
`--cluster-id`	string (repeatable)	—	Filter by cluster ID
`--namespace`	string (repeatable)	—	Filter by namespace
`--kind`	string (repeatable)	—	`Deployment`, `StatefulSet`, or `DaemonSet`
`--team`	string (repeatable)	—	Filter by team
`--department`	string (repeatable)	—	Filter by department
`--has-hpa`	bool	unset	Only applied when set: `--has-hpa` returns workloads with a HorizontalPodAutoscaler, `--has-hpa=false` returns workloads without one
`--min-cost-hourly`	string	—	Minimum hourly cost, e.g. `0.50`

Example

bash

kubeadapt get workloads --cluster-id c1a2b3c4-d5e6-7890-abcd-ef1234567890 --namespace payments

Sample output:

plaintext

1╭──────────────────────────────────────┬────────────┬───────────┬───────────────┬─────────────┬──────────┬─────────┬─────────┬─────────╮
2│ ID                                   │ Cluster    │ Namespace │ Name          │ Kind        │ Replicas │ CPU req │ Mem req │ $/hr    │
3├──────────────────────────────────────┼────────────┼───────────┼───────────────┼─────────────┼──────────┼─────────┼─────────┼─────────┤
4│ b9f1a342-7c5e-4d8a-9e2b-1234567890ab │ production │ payments  │ api-gateway   │ Deployment  │ 3/3      │ 1.50    │ 3.0 GiB │ $0.1800 │
5│ 2d7c9e10-4b8a-4f21-9c3d-5e6f7a8b9c0d │ production │ cache     │ redis-primary │ StatefulSet │ 1/1      │ 0.50    │ 4.0 GiB │ $0.0600 │
6│ 7a1b2c3d-9e8f-4a5b-8c7d-6e5f4a3b2c1d │ production │ jobs      │ worker        │ Deployment  │ 5/5      │ 2.50    │ 5.0 GiB │ $0.4300 │
7╰──────────────────────────────────────┴────────────┴───────────┴───────────────┴─────────────┴──────────┴─────────┴─────────┴─────────╯
8
9Showing 3 (limit 100). End of results.

See API: Workloads for the full response schema.

get workload

kubeadapt get workload <workload-uid>

Shows a single workload by its Kubernetes metadata.uid.

Arguments

Argument	Description
`workload-uid`	Kubernetes `metadata.uid` of the workload (required)

Flags

Flag	Type	Default	Description
`--cluster-id`	string	—	Cluster to read the workload from. Needed only when the UID exists in more than one of your clusters.

A UID can exist in more than one cluster, for example when a cluster is registered twice. The command then fails and prints the cluster IDs to choose from, each as a ready-to-paste --cluster-id flag.

Example

bash

kubeadapt get workload b9f1a342-7c5e-4d8a-9e2b-1234567890ab
kubeadapt get workload b9f1a342-7c5e-4d8a-9e2b-1234567890ab --cluster-id c1a2b3c4-d5e6-7890-abcd-ef1234567890

get pods

kubeadapt get pods <workload-uid>

Lists pods belonging to a workload.

Arguments

Argument	Description
`workload-uid`	Kubernetes `metadata.uid` of the parent workload (required)

Flags

Flag	Type	Default	Description
`--cluster-id`	string	—	Only list pods from this cluster. Without it, pods from every cluster that holds the workload UID are listed.
`--namespace`	string (repeatable)	—	Filter by namespace
`--node-uid`	string (repeatable)	—	Filter by node UID
`--phase`	string	—	Filter by pod phase (`Pending`, `Running`, `Succeeded`, `Failed`, `Unknown`)
`--qos-class`	string	—	Filter by QoS class (`Guaranteed`, `Burstable`, `BestEffort`)
`--has-hostpath`	bool	unset	Only applied when set: `--has-hostpath` returns pods with hostPath volumes, `--has-hostpath=false` returns pods without them
`--has-emptydir`	bool	unset	Only applied when set: `--has-emptydir` returns pods with emptyDir volumes, `--has-emptydir=false` returns pods without them
`--host-network`	bool	unset	Only applied when set: `--host-network` returns pods using the host network, `--host-network=false` returns pods that don't

Example

bash

kubeadapt get pods b9f1a342-7c5e-4d8a-9e2b-1234567890ab --phase Running

get nodes

Lists nodes in your clusters. Node cost has no cost mode, so this command rejects --cost-mode.

Flags

Flag	Type	Default	Description
`--cluster-id`	string (repeatable)	—	Filter by cluster ID
`--node-group`	string (repeatable)	—	Filter by node group name
`--instance-type`	string	—	Instance type, e.g. `m5.large`
`--zone`	string	—	Availability zone
`--architecture`	string	—	`amd64` or `arm64`
`--capacity-type`	string	—	`on-demand` or `spot`
`--is-spot`	bool	unset	Only applied when set: `--is-spot` returns spot nodes, `--is-spot=false` returns the rest
`--is-ready`	bool	unset	Only applied when set: `--is-ready` returns ready nodes, `--is-ready=false` returns nodes that are not ready

Example

bash

kubeadapt get nodes --cluster-id c1a2b3c4-d5e6-7890-abcd-ef1234567890 --capacity-type spot

get node

kubeadapt get node <node-uid>

Shows a single node by its Kubernetes metadata.uid.

Arguments

Argument	Description
`node-uid`	Kubernetes `metadata.uid` of the node (required)

Flags

Flag	Type	Default	Description
`--cluster-id`	string	—	Cluster to read the node from. Needed only when the UID exists in more than one of your clusters.

Example

bash

kubeadapt get node 4e1f2a3b-6c7d-4e8f-9a0b-1c2d3e4f5a6b
kubeadapt get node 4e1f2a3b-6c7d-4e8f-9a0b-1c2d3e4f5a6b --cluster-id c1a2b3c4-d5e6-7890-abcd-ef1234567890

get node-groups

Lists node groups for your clusters. The endpoint returns every group in one response, so this command rejects the pagination flags and --cost-mode.

Flags

Flag	Type	Default	Description
`--cluster-id`	string (repeatable)	—	Filter by cluster ID

Example

bash

kubeadapt get node-groups --cluster-id c1a2b3c4-d5e6-7890-abcd-ef1234567890

get node-group

kubeadapt get node-group <name>

Shows a single node group by name.

Arguments

Argument	Description
`name`	Node group name (required)

Flags

Flag	Type	Default	Description
`--cluster-id`	string	—	Cluster ID that owns the node group (required, exactly one)

Example

bash

kubeadapt get node-group prod-mixed --cluster-id c1a2b3c4-d5e6-7890-abcd-ef1234567890

get recommendations

Lists optimization recommendations.

Flags

Flag	Type	Default	Description
`--cluster-id`	string (repeatable)	—	Filter by cluster ID
`--namespace`	string (repeatable)	—	Filter by namespace
`--recommendation-type`	string	—	Recommendation type (`workload_rightsizing`)
`--status`	string	—	`pending`, `applied`, `dismissed`, or `archived`
`--priority`	string	—	`low`, `medium`, or `high`
`--risk-level`	string	—	`low`, `medium`, or `high`
`--resource-type`	string	—	`Deployment`, `StatefulSet`, `DaemonSet`, `Pod`, or `Node`
`--workload-uid`	string (repeatable)	—	Filter by workload UID
`--min-savings-hourly`	string	—	Minimum hourly savings, e.g. `0.10`

Example

bash

kubeadapt get recommendations --recommendation-type workload_rightsizing --status pending

Sample output:

plaintext

1╭──────────────────────────────────────┬────────────┬──────────────────────┬───────────────────────┬──────────┬────────┬────────────╮
2│ ID                                   │ Cluster    │ Type                 │ Resource              │ Priority │ Risk   │ Savings/hr │
3├──────────────────────────────────────┼────────────┼──────────────────────┼───────────────────────┼──────────┼────────┼────────────┤
4│ f47ac10b-58cc-4372-a567-0e02b2c3d479 │ production │ workload_rightsizing │ payments/api-gateway  │ high     │ low    │ $0.0586    │
5│ 3c9e1f2a-7b4d-4e8a-9f6c-1d2e3f4a5b6c │ production │ workload_rightsizing │ monitoring/prometheus │ medium   │ low    │ $0.0253    │
6│ 8e2d4c6b-1a3f-4b5e-9d7c-2f4e6a8c0b1d │ production │ workload_rightsizing │ default/nginx-ingress │ low      │ medium │ $0.0085    │
7╰──────────────────────────────────────┴────────────┴──────────────────────┴───────────────────────┴──────────┴────────┴────────────╯
8
9Showing 3 (limit 100). End of results.

See Right-sizing for how recommendations are generated.

get recommendation

kubeadapt get recommendation <id>

Shows a single recommendation by ID.

Arguments

Argument	Description
`id`	Recommendation UUID (required)

Example

bash

kubeadapt get recommendation f47ac10b-58cc-4372-a567-0e02b2c3d479 -o json

get teams

Lists teams with cost attribution.

Flags

Flag	Type	Default	Description
`--department-id`	string (repeatable)	—	Filter by department ID
`--origin`	string (repeatable)	—	Filter by origin: `k8s` (auto-discovered from labels) or `kubeadapt` (created in the dashboard)

Example

bash

kubeadapt get teams -o json

get team

kubeadapt get team <team-id>

Shows a single team by ID.

Arguments

Argument	Description
`team-id`	Team UUID (required)

Example

bash

kubeadapt get team f47ac10b-58cc-4372-a567-0e02b2c3d479

get team-assignments

kubeadapt get team-assignments <team-id>

Lists the workloads, namespaces, and persistent volumes assigned to a team.

Arguments

Argument	Description
`team-id`	Team UUID (required)

Flags

Flag	Type	Default	Description
`--entity-type`	string	—	Filter by entity type (`workload`, `namespace`, `pv`)
`--cluster-id`	string (repeatable)	—	Filter by cluster ID
`--source`	string	—	Filter by assignment source: `k8s_label`, `user_manual`, `namespace_auto`

Example

bash

kubeadapt get team-assignments f47ac10b-58cc-4372-a567-0e02b2c3d479 --entity-type workload

get departments

Lists departments with cost attribution.

Flags

Flag	Type	Default	Description
`--origin`	string (repeatable)	—	Filter by origin: `k8s` (auto-discovered from labels) or `kubeadapt` (created in the dashboard)

Example

bash

kubeadapt get departments

get department

kubeadapt get department <dept-id>

Shows a single department by ID.

Arguments

Argument	Description
`dept-id`	Department UUID (required)

Example

bash

kubeadapt get department a1b2c3d4-e5f6-7890-abcd-ef1234567890

get namespaces

Lists namespaces with their hourly cost.

Flags

Flag	Type	Default	Description
`--cluster-id`	string (repeatable)	—	Filter by cluster ID
`--min-cost-hourly`	string	—	Minimum hourly cost, e.g. `0.05`

Example

bash

kubeadapt get namespaces --cluster-id c1a2b3c4-d5e6-7890-abcd-ef1234567890

To list the namespaces assigned to a team, use kubeadapt get team-assignments <team-id> --entity-type namespace.

get namespace

kubeadapt get namespace <name>

Shows a single namespace by name.

Arguments

Argument	Description
`name`	Kubernetes namespace name (required)

Flags

Flag	Type	Default	Description
`--cluster-id`	string	—	Cluster ID that owns the namespace (required, exactly one)

Example

bash

kubeadapt get namespace payments --cluster-id c1a2b3c4-d5e6-7890-abcd-ef1234567890

health

kubeadapt health

Checks that the configured API URL is reachable. No authentication required. Exits non-zero if the server is unreachable or returns a non-2xx status.

Example

bash

kubeadapt health

auth

Manages stored credentials. See Authentication for full details.

Subcommand	Description
`auth login`	Prompts for an API key, verifies it against the API, then saves it to the config file
`auth status`	Verifies the active API key against the API and shows the masked key, API URL, and organization
`auth logout`	Removes the stored API key from the config file

version

Prints the binary version, commit hash, build date, Go version, and OS/architecture.

bash

kubeadapt version

Example output:

plaintext

kubeadapt 0.3.0
  Commit:     <commit>
  Built:      <build time>
  Go version: <go version>
  OS/Arch:    darwin/arm64

kubeadapt version -o json returns the keys version, commit, built, go_version, and os_arch.

completion

Generates shell completion scripts. See Shell completions for setup instructions per shell.

bash

kubeadapt completion [bash|zsh|fish|powershell]