Command Bar

The command bar is Buoy’s primary surface. You type a kubectl-style command and Buoy opens a live-updating table or detail view that matches the columns kubectl would print. Pipes refine, sort, group, or hand the rows off to a different renderer. Slash commands toggle app state, jump to other views, and run RBAC or PromQL workspaces.

Open the command bar with :, ;, or Cmd+L (Ctrl+L on Linux and Windows). Press Esc to blur it.

Anatomy of a Command
Flags
Positional Names and List Mode
Pipe Operators
Filter Expressions and CEL
Slash Commands
Saved Aliases
History

Anatomy of a Command

<resource> [<name>] [flags] [| pipe-operator ...]

The resource token is whatever you would pass to kubectl get: a full name (pods, deployments, nodes), a short name (po, deploy, no), or a CRD plural (workflows, rollouts). Resource resolution is delegated to apiserver discovery, so any name kubectl accepts works in Buoy.

Worked example:

pods -n production -l app=api -L env | sortby cpu(metadata.annotations["last-cpu"]) desc | grep nginx

This lists pods in production matching the label selector app=api, adds a column for the env label, sorts descending by a CEL expression, then keeps only rows whose visible cells contain nginx.

Flags

Every flag accepts --flag value and --flag=value. Short flags follow the kubectl convention.

Flag	Long form	Value	Description
`-c`	`--context`	string	Run against a specific kubeconfig context.
	`--contexts`	comma list	Fan out across an explicit list of contexts. Watches start once per context and rows merge client-side.
	`--all-contexts`	(none)	Fan out across every context in your kubeconfig.
`-n`	`--namespace`	string	Scope to a namespace.
`-A`	`--all-namespaces`	(none)	List across every namespace.
`-l`	`--selector`	label selector	Server-side label selector. Repeat to add more clauses; multiple `-l` flags join with commas.
`-f`	`--field-selector`	field selector	Server-side field selector. Repeatable.
`-L`		label key	Add a column showing a label value. Repeatable.
`-F`		JSON path	Add a column showing the value at a dotted path inside `row.object`. Repeatable.
	`--ann`, `--show-annotation`	annotation key	Add a column showing an annotation value. Repeatable.
	`--filter-annotation`	annotation selector	Client-side annotation filter. Accepts `key=value`, `key!=value`, `key` (present), `!key` (absent), comma-separated.
`-o`	`--output`	`wide`	Show every column the apiserver returns, including ones the default view hides. `-owide` and `--output=wide` both work.

Examples:

pods --context=prod-eu --namespace=kube-system
deployments -A -L env -L region
pods -l tier=backend,role=worker
nodes --filter-annotation 'team=platform,!deprecated'

A few flags only make sense at the top of the pipeline. Inside a terminal view step (| allocation, | neighbors), Buoy accepts -L, -F, --ann, and -o wide but rejects scoping flags. Put -n, -l, -c, and friends before the pipe.

Positional Names and List Mode

A bare resource lists rows. Adding a name selects a single object and opens its detail view:

pods                      # list pods
pods my-pod               # open detail view for my-pod
deployments api-server    # open detail view for the api-server Deployment

Only one positional is allowed. A second positional is a parse error.

Pipe Operators

Pipes are split on a | surrounded by whitespace or at the end of the input. Quoted segments preserve their literal |.

Steps fall into two groups. Standard steps refine the row stream and can be chained. Terminal steps swap the table for a different renderer and must appear last.

Standard Steps

Step	Aliases	Description
`grep <text>`		Case-insensitive substring match across every visible cell.
`filter <expr>`	`where`	CEL expression evaluated against `row.object`. Keep rows where the expression is truthy.
`sortby <expr> [asc\|desc]`	`sort`, `sort-by`	Stable sort by a CEL expression. Default direction is ascending. Rows whose value is null or undefined sort last regardless of direction.
`filter-annotation <selector>`	`filter-ann`	Annotation filter that compiles to a CEL `filter`. Single token (`team=platform`, `!deprecated`) or `key OP <expr>` for arbitrary operators.

Worked examples:

pods | grep Running
pods | filter status.phase == "Running"
pods | where !has(metadata.labels.deprecated)
pods | sortby cpu(spec.containers[0].resources.requests.cpu) desc
pods | filter-annotation team!=frontend

Pipeline steps are applied client-side after the watch. Editing them does not restart the watch or re-list from the apiserver.

Terminal Views

Step	Aliases	Source resource	Description
`allocation`	`alloc`	`nodes`	Per-node CPU and memory allocation bars, chunked by pod and colored by namespace.
`neighbors`	`neighbours`	`pods`	Resolves the distinct nodes the selected pods run on and renders the allocation view for those nodes.
`groupby <expr>`	`group`, `group-by`	any	Buckets rows by the value of a CEL expression and renders one card per bucket. For pods, each card draws a square per pod colored by phase. Clicking a bucket drills into a filtered table.
`clipboard [<expr>]`	`copy`	any	Projects each row through the optional CEL expression and copies the joined result to the system clipboard. Without an expression, copies the visible table as TSV.
`dashboard [<slug>]`	`dash`	any	Opens a Prometheus dashboard scoped to the command. With a name positional, scoped to that single resource. The optional slug picks a specific dashboard; without it, the first dashboard whose `kinds` includes the resolved kind wins.

Worked examples:

nodes | allocation -L zone
pods -l app=api | neighbors
pods -A | groupby metadata.namespace
pods | clipboard metadata.name
pods nginx-abc | dashboard
deployments -l app=api | dashboard psi

allocation and neighbors accept additional column flags (-L, -F, --ann, -o wide) inline:

nodes | alloc -L env -F spec.unschedulable -o wide

Filter Expressions and CEL

filter, where, sortby, and groupby evaluate CEL expressions against each row’s object. Buoy’s CEL subset supports the dotted paths, indexing, arithmetic, and boolean operators you would expect, plus a set of helpers tuned for Kubernetes.

Helpers

Helper	Purpose
`has(path)`	Path existence. Missing parents return false instead of throwing.
`size(x)`	Length of a string, array, or map.
`contains(s, sub)`	Substring test.
`keys(map)`	Map keys, sorted.
`values(map)`	Map values, sorted by key.
`entries(map)`	Map as `[{key, value}, ...]`, sorted by key.
`label('k')`	Reads `metadata.labels["k"]`.
`annotation('k')`	Reads `metadata.annotations["k"]`.
`cpu(quantity)`	Kubernetes CPU quantity to millicores. `'100m'` returns 100, `'1'` returns 1000.
`memory(quantity)`, `quantity(q)`	Memory or storage quantity to bytes. `'1Gi'` returns 1073741824.
`compare(a, b)`	Heterogeneous quantity compare. Returns `a - b`, or null when the operands are different families.
`humanize(bytes)`	Bytes to a string like `"1.5Gi"`.
`duration(seconds)`	Seconds to a string like `"5d3h2m"`.
`age(timestamp)`	Seconds since an RFC3339 timestamp. Negative for future times.
`ago(timestamp)`	Shorthand for `duration(age(timestamp))`. Returns an empty string when the input is unparseable.
`now()`	Current Unix seconds.
`truncate(s, n)`	First `n` characters, with an ellipsis when truncation happened.
`short(s)`	First 7 characters of a string (handy for git SHAs).
`string(x)`, `int(x)`	Coerce to string or truncate to integer.
`b64encode(s)`, `b64decode(s)`	UTF-8 base64 round trip. Decode returns the original on failure so broken Secret values render visibly.
`context()`	Source context name for the row, populated under multi-context fan-out.
`kubectl()`	Render the row as a copy-pasteable `kubectl get ...` command line.
`node()`, `service()`, `services()`, `deployment()`, `pdb()`, `pdbs()`, `pvc()`, `pvcs()`	Cross-resource joins. They look up the related object in the same context. The plural forms return arrays; the singular forms return the first match.

Examples

pods | filter status.phase == "Running"
pods | filter !has(metadata.labels.deprecated)
pods | filter cpu(spec.containers[0].resources.requests.cpu) > 500
pods | filter age(metadata.creationTimestamp) > 86400
secrets | filter size(data) > 5
pods | filter contains(string(spec.containers[0].image), "nginx")
pods | sortby memory(spec.containers[0].resources.limits.memory) desc
pods --contexts=prod-us,prod-eu -A | groupby context()

Slash Commands

Slash commands intercept input that starts with /. They never collide with kubectl resource names.

Command	Aliases	Usage	Description
`/ctx`	`/context`	`/ctx [name \| -]`	Set or clear the default context. `-` or no argument clears.
`/ns`	`/namespace`	`/ns [name \| -]`	Set or clear the default namespace.
`/contexts`	`/clusters`	`/contexts [a,b,c \| -]`	Open the contexts viewer, or set a multi-context default (comma list, no spaces). `-` clears.
`/as`		`/as <user> [--groups g1,g2] [--uid x]`	Activate Kubernetes impersonation. `/as` alone or `/as -` clears it.
`/dashboards`	`/dash`	`/dashboards`	Open the Prometheus dashboards manager.
`/prom`	`/metrics`	`/prom [expr]`	Open the PromQL workspace, optionally pre-filled.
`/top`		`/top pods\|nodes [flags]`	Live CPU and memory table with sparklines. Accepts the same scoping flags as `pods` or `nodes`, plus `--interval <duration>` (default 5s, minimum 1s).
`/logs`		`/logs <selector>`	Aggregated tail across every pod matching the selector. Defaults to all namespaces when no namespace is set. Accepts `--tail`, `--since`, `-p`/`--previous`, `-C`/`--container`, `-f`/`--no-follow`.
`/explain`		`/explain <resource>`	Open the schema viewer, in the spirit of `kubectl explain`.
`/who-can`	`/whocan`	`/who-can <verb> <resource> [-n ns]`	RBAC explorer. Shows which subjects can perform a verb.
`/cols`	`/columns`	`/cols <resource> [+L\|+ann\|+F\|-L\|-ann\|-F key]`	Manage default extra columns for a resource kind.
`/pf`	`/portforwards`, `/port-forwards`	`/pf`	Open the port-forwards manager.
`/settings`	`/prefs`	`/settings`	Open settings. Also reachable with `Cmd+,`.
`/link`	`/share`	`/link`	Copy a deep link (`buoy://...`) to the current view.
`/save`		`/save <name> <body>`	Save an alias. `/save <name>` with no body removes the alias.
`/unsave`		`/unsave <name>`	Delete an alias.
`/aliases`	`/saved`	`/aliases`	List every saved alias.

Plugins can register additional slash commands and full views. See plugins/commands.md.

Saved Aliases

Aliases give you short names for long commands. Each alias is a literal substitution: when you type /<alias-name>, Buoy replaces it with the saved body and reparses.

/save quick-web pods -n default -l app=web,tier=api
/quick-web                  # expands to: pods -n default -l app=web,tier=api
/save quick-web             # delete by saving with no body
/aliases                    # list all aliases

Aliases live in your preferences and survive restarts. They appear inline in the command-bar autocomplete alongside built-in slash commands.

History

Buoy keeps the last 1000 commands you have run. Press the Up and Down arrow keys inside the command bar to walk through them. Clear history from Settings, Command history.

Edit this page on GitLab