Fields
Every resource in the unikraft CLI (instances, images, services, volumes, and more) has a set of fields.
Fields are the named pieces of data the platform stores about a resource, such as its name, state, image, or memory resources.
The same fields power table output, sorting, filtering, and editing, so once you learn a resource's field names you can use them everywhere.
This page covers what fields are, how to control which fields appear, how to sort and filter on them, and how to edit them with edit.
The field model
To see all fields in the model, run unikraft instances list --help or unikraft instances get --help.
To view instances' values for all these fields, use unikraft instances list -fall or unikraft instances get <name> -fall.
To view the default set of fields and their current values for an instance, inspect it with get.
The output is a tree of fields, where some fields hold scalars and others hold nested objects or lists.
Code
Field paths
Use dot-separated paths to address nested fields. A path walks down the tree, one field name per segment.
Code
The --field, --sort, --filter flags, and the edit command, all use these same paths (described below).
Choosing which fields to display
Listing resources prints a default set of columns.
Use --field (short form -f) to select which fields to display.
When you pass a parent field, the CLI expands it into a column for each of its child fields.
Code
For a single instance, get with --field shows the same nested structure:
Code
Pass a specific field path to display only that value.
Code
Code
You can pass fields as a comma-separated list, or repeat --field several times.
Code
Code
Adding and removing from the default field set
Prefix a field name with + to add it to the default set, or - to remove it.
This lets you fine-tune the output without listing every field you want.
Code
The networks field is absent because -networks removed it, and timing appears at the end because +timing added it.
The same syntax works with list:
Code
Sorting
Use --sort with a field path to order the output by that field.
Code
Filtering
Use --filter with a field path and an operator to show only the resources that match.
Code
--filter is available on the list and delete subcommands throughout the unikraft CLI.
The filter expression language supports nested paths, wildcards, regular expressions, and combining expressions. See the filter expression reference for the full grammar, operators, and examples.
The --until flag
The --until flag uses the same expression syntax as --filter.
--until is available on the wait subcommand.
The command polls until every targeted resource matches the expression.
Code
Editing fields
The edit command modifies a resource's fields in place, and the create command uses the same flags when creating a new resource.
edit prints a diff of the change, where + lines are additions and -/+ pairs show a replaced value.
Setting a field with --set
Use --set <path>=<value> to set or replace a field.
Setting a field that doesn't exist yet creates it, including any parent fields.
Many common fields also have dedicated shorthand flags—for example, --memory instead of --set resources.memory=.
These are shortcuts for --set and are a bit easier to remember and type.
You don't need to use field-based editing for fields that have a dedicated flag.
Code
Adding and removing with --add and --del
Use --add <name>=<value> to append to a list or map field, and --del <name> to remove an entry from one.
For example, remove an environment variable:
Code
The --add flag works the same way, appending the given value instead of removing it.
Code
You can combine --set, --add, and --del flags in a single edit invocation.
List and map fields
Each flag carries exactly one element, so a field holding a list or a map takes one flag per entry. The CLI never splits a value on commas—a comma inside a value is part of that value.
Code
To pass a whole list or map in a single flag, write it as JSON instead.
Code
Visual editing
Pass --visual to open the resource in your editor and edit its fields interactively.
The CLI launches the program named by the $VISUAL or $EDITOR environment variable.
Code
If neither variable has a value, the command fails with no editor set: please set $VISUAL or $EDITOR.
When you save and close the editor, the CLI applies your changes and prints the resulting diff.
Code
Dry-run
Pass --dry-run to any edit or create command to print the diff of what would change without actually applying it.
This is useful for previewing changes before committing them, and pairs especially well with --visual.
Code
Filter expression reference
The --filter and --until flags accept filter expressions that match resources based on their field values.
The syntax extends the containerd filter grammar with negated regex matching, wildcards, and alternative quoting.
Grammar
Code
A quoted-string uses Go string syntax (double quotes with standard
backslash escapes: \n, \t, \\, \", \xNN, \uNNNN, \UNNNNNNNN,
octal \NNN).
A regex-string may only appear after ~= or !~=.
You can delimit it with / or | instead of ", which is convenient when the pattern contains double-quotes or backslashes (for example, name~=/[abc]{0,2}/ or path~=|foo/bar|).
An unquoted-string is any run of non-whitespace, non-comma characters.
Operators
| Operator | Alias | Description | Example |
|---|---|---|---|
== | = | Equals | state==running |
!= | !== | Not equals | state!=stopped |
~= | Matches regular expression | name~="^web-.*" | |
!~= | Doesn't match regular expression | name!~="^test-" | |
> | Greater than | resources.vcpus>2 | |
< | Less than | resources.vcpus<4 | |
>= | Greater than or equal | resources.vcpus>=2 | |
<= | Less than or equal | resources.vcpus<=4 | |
| (none) | Field is present and non-empty | description |
Regular expressions use Go regexp syntax.
Comparisons
>, <, >=, and <= order a field's value against the given value.
They work on numeric fields (resources.vcpus>2) and on timestamp fields (timestamps.created<2024-01-01T00:00:00Z), but not on strings or booleans—those only support == and !=.
Code
Absolute time
Timestamp fields accept most common formats for an absolute point in time, so you don't need to look up or match one specific layout. For example:
- RFC3339, with or without fractional seconds:
2024-01-01T00:00:00Z - A date and time without a zone offset (interpreted as UTC):
2024-01-01T00:00:00or"2024-01-01 00:00:00"(quote values containing a space) - A bare date (midnight UTC):
2024-01-01 - A Unix timestamp:
1704067200
Code
Relative time
Timestamp fields also accept a relative duration on the right-hand side of >, <, >=, or <=, which is compared against the field's age (how long ago it occurred), rather than the timestamp itself.
So timestamps.created<7d matches resources created less than 7 days ago, and timestamps.created>30d matches resources older than 30 days.
A duration is a sequence of numbers with a unit, and units can be combined (for example 1d12h):
| Unit | Meaning |
|---|---|
s | seconds |
m | minutes |
h | hours |
d | days |
w | weeks |
y | years |
Code
Wildcards
A * in a field path iterates over all entries of a map or array field.
The wildcard can appear at any level, and you can chain wildcards.
Code
Negation semantics with wildcards: positive operators (==, ~=) match if
any entry meets the condition.
Negated operators (!=, !~=) match only if all entries meet the condition (that is, no entry matches the negated pattern).
Indexed access
You can also access array elements by zero-based numeric index.
Code
Combining expressions
And (comma-separated within one flag)
Comma-separated selectors within a single --filter value must all match for the filter to include a resource.
Code
Or (repeated flags)
When you specify --filter several times, the filter includes a resource if it matches any of the expressions.
Code
Combining both operators
The two mechanisms compose:
Code
This matches resources that are (running in fra0) or (stopped in was1).
Special fields
The metro field receives special handling: when present in a filter, it restricts which metros the CLI queries rather than filtering results after the fact.
This means --filter metro==fra0 avoids fetching data from other metros entirely.
Examples
Code