Skip to content

kuke get

List or describe resources.

kuke get <resource> [NAME] [flags]
kuke g   <resource> [NAME] [flags]      # alias

Resources: realm, space, stack, cell, container, image, blueprint, config. Each subcommand also accepts its plural (realms, spaces, …, images, blueprints, configs) and a short alias (r, sp, st, ce, co, img, bp, cfg).

Common flags

Flag Description
--output, -o Output format: yaml, json, table, wide. Default: table for both a list and a single named resource (#1323). wide accepted by every kuke get <kind> for symmetry; per-kind wide columns vary (see each kind).
--selector, -l Label selector (kubectl-style) to filter list results. Supports =, ==, !=, existence (key), absence (!key), and comma-separated AND (e.g. env=prod,tier!=db or env,!debug). Rejected with a positional NAME.

Plus all global flags. Every kuke get <kind> accepts the explicit --no-daemon flag to bypass the daemon (inherited as a persistent flag from the parent get command); KUKEON_NO_DAEMON=true and --run-path /opt/kukeon (which auto-promotes the command into in-process mode) work as well.

Hierarchy flags

Each subcommand takes the flags that scope the query:

Subcommand Scope flags
get realm [name] none (realms are top-level)
get space [name] --realm (default default)
get stack [name] --realm, --space
get cell [name] --realm, --space, --stack
get container [name] --realm, --space, --stack, --cell
get image [ref] --realm (omit for cross-realm listing; defaults to default on the describe path)
get blueprint [name] --realm, --space, --stack (no --cell — Blueprints are never cell-scoped)
get config [name] --realm, --space, --stack (no --cell — Configs are never cell-scoped)

All scope flags default to default. See the realm default note.

Behavior

  • List (no positional arg): returns every resource matching the scope flags. Default output is a table.
  • Single (positional arg): returns the one matching resource. Default output is a single table row with the same columns as the list view (#1323, kubectl parity); -o wide renders the single wide row. The full document is reached via -o yaml / -o json. (Breaking change: scripts that relied on a bare named get emitting YAML must switch to -o yaml.)

Default tables and -o wide columns

Per-kind column contracts. The default table is what kuke get <kind> (no -o wide) emits; -o wide appends the listed extras.

Kind Default columns -o wide appends
realm NAME STATE AGE NAMESPACE
space NAME REALM STATE AGE EGRESS NET-DEFAULTS
stack NAME REALM SPACE STATE AGE (none — stack carries no wide-only signals)
cell NAME REALM SPACE STACK STATE SYNC AGE CONTAINERS BRIDGE DIVERGENCE
container NAME REALM SPACE STACK CELL STATE RESTARTS AGE IMAGE EXIT
image NAME REALM CREATED (cross-realm default) DIGEST
blueprint NAME REALM SPACE STACK AGE (none)
config NAME REALM SPACE STACK AGE (none)

SYNC (InSync/OutOfSync/-) is computed for cells that carry a kukeon.io/config=<name> lineage label; non-lineage cells render -. The -o wide DIVERGENCE column expands an OutOfSync cell with a one-line summary of what diverged (image, env, mounts, …). See kuke restart for the reconcile verb.

-o wide on space surfaces the egress allowlist (EGRESS) and the cell-default-deny posture (NET-DEFAULTS yes/no).

-o wide on container surfaces the resolved container image reference (IMAGE) and the <exitCode>/<exitSignal> pair (EXIT) when either field is non-zero. The RESTARTS column lives in the default table; CGROUP, ROOT, and IMAGE (as defaults) were retired in v0.6.0 — see "Retired in v0.6.0" below.

# Table of realms — the dev-init parity check expects this column shape
sudo kuke get realms
NAME         STATE  AGE
-----------  -----  ---
default      Ready  <age>
kuke-system  Ready  <age>

# Same data with the namespace surfaced
sudo kuke get realms -o wide
NAME         STATE  AGE  NAMESPACE
-----------  -----  ---  ---------------------
default      Ready  <a>  default.kukeon.io
kuke-system  Ready  <a>  kuke-system.kukeon.io

# Single realm as YAML
sudo kuke get realm default -o yaml

# Single realm as JSON
sudo kuke get realm default -o json

# Spaces in the default realm
sudo kuke get spaces --realm default

# Cells in a stack — SYNC column flags Config-lineage drift; OutOfSync points at `kuke restart`
sudo kuke get cells --realm default --space default --stack default
NAME           REALM    SPACE    STACK    STATE  SYNC       AGE
-------------  -------  -------  -------  -----  ---------  ---
work-001       default  default  default  Ready  InSync     12m
work-002       default  default  default  Ready  OutOfSync  3m
shell          default  default  default  Ready  -          1h

# Containers — RESTARTS column (process bounces since cell start); -o wide adds IMAGE EXIT
sudo kuke get containers --realm default --space default --stack default --cell work-001 -o wide

# All containers in a cell
sudo kuke get containers --realm default --space default --stack default --cell hello-world

# Images across every realm (cross-realm by default)
sudo kuke get images

# Narrow to one realm; -o wide adds CREATED and DIGEST columns
sudo kuke get image --realm kuke-system -o wide

# Describe a single image as YAML (defaults --realm to `default` on this path)
sudo kuke get image docker.io/library/nginx:alpine -o yaml

# List every daemon-stored CellBlueprint bound to the kuke-system realm
sudo kuke get blueprints --realm kuke-system

# Show one CellConfig as YAML
sudo kuke get config kukeon-dev --realm kuke-system -o yaml

Label selector (-l/--selector)

Filter list results by label query. The flag is wired on every kuke get <kind> verb (realm, space, stack, cell, container).

# Cells labeled env=prod
sudo kuke get cell -l env=prod

# Cells with the `debug` label absent
sudo kuke get cell -l '!debug'

# Comma-separated AND
sudo kuke get cell -l 'env=prod,tier!=db'

A positional NAME plus -l is rejected — a selector queries the list path, a name queries the single-resource path; mixing them is ambiguous. Malformed selectors fail before any controller call.

get vs refresh

get reads metadata. It does not reconcile or update .status. If you want the status to reflect the live runtime state (after a crash, or after containerd reported a change), run kuke refresh first.

Retired in v0.6.0

  • --show-controllers / CGROUP column — the cgroup-controllers signal on -o wide cell/container tables is gone. The state-of-cgroup-controllers check moved into kuke status's host section and kuke doctor cgroups.
  • IMAGE as a default container column — IMAGE is now an -o wide extension only. Use kuke get container -o wide or -o yaml to surface it.
  • ROOT column — retired entirely.
  • kuke image get / kuke image ls / kuke image list — folded into kuke get image[s] with no alias window. See the kuke get image examples below.