Output Formatting

The ODIN CLI supports various output formats to accommodate different needs, such as human-readable formats for direct interaction and machine-readable formats for scripts and automation.

Basics#

The output format can be set using the --format flag. If omitted, the default format is used that is specific to each command. If values to be printed in tables or as a value are objects or arrays, they are automatically converted to JSON format.

I.e. the Servers object has a hash map of ports. If you want to print the published ports of your server, you can use the following command:

odin fleet servers list --format="table(id,addr,ports)"

This will output a table with the server ID, IP address, and the ports object in JSON format. You can also access nested properties by using the dot syntax. If you want to print the published game port of your server, you can use the following command:

odin fleet servers list --format="table(id,addr,ports['Game Port'].publishedPort)"

The Game Port is the name of the port configuration you created in the server configuration. The publishedPort is the port that is actually used by the server.

Default Output#

The default format is human-readable and designed to be intuitive for each command.

JSON Output#

The json format outputs the command results in JSON format, conforming to the API specifications. This is useful for processing data programmatically.

odin <command> --format=json

Table Output#

The table(propertyList) format prints the result in a table format. The propertyList is a comma-separated list of properties you want to display as table columns. Nested properties can be accessed using the dot syntax (e.g., serverConfig.id).

odin <command> --format="table(id,name)"

Example:

odin fleet servers list --format="table(id,addr,ports['Game Port'].publishedPort)"

This would display a table with columns with the id, the servers IP address and the published game port.

Flattened Output#

The flattened[noPad,separator='->'](propertyList) format prints a simple key value pair output, where each property is displayed on a new line. The separator attribute allows you to define a custom separator between the key and value.

odin <command> --format="flattened(id,name)"

Optional Attributes:

• noPad: Disables padding, resulting in a more compact output.
• separator: Changes the default separator (:) to any other character(s).

Example:

odin fleet servers list --format="flattened[separator='->'](id,name)"

This would output:

id->12345
name->MyServer

Value Output#

The value[separator='->'](propertyList) format prints only the values of the specified properties in a single line, separated by the chosen separator (default is tab).

odin <command> --format="value[separator=':'](id,name)"

Optional Attributes:

• separator: An optional attribute that lets you define a custom separator for the values.

Examples:

odin fleet servers list --format="value[separator=':'](id,name)"

This would output:

12345:MyServer

It’s a powerful tool for extracting specific information from the output of a command. I.e. it’s super useful in scripts or automation tasks. For example when creating an item you can use the value format to just get the ID of the created item. That can easily be used in the next command.

IMAGE_ID=$(
  odin fleet images create \
  --name="Example Image" \
  --type="dockerImage" \
  --docker-image="example/example-image:latest" \    
  --registry-id=1 \
  --force \
  --format="value(id)")
  
echo "Created image with ID: $IMAGE_ID"

This would store the ID of the created image in the IMAGE_ID variable.

Advanced Property Lists#

Property lists can be very flexible and powerful, especially when dealing with nested data or arrays. Here are some advanced examples:

Accessing Nested Properties#

odin fleet servers list --format="value[separator=':'](id,serverConfig.id)"

Output:

12345:67890

Indexing Arrays#

odin fleet configs list --format="value[separator=':'](id,name,env[0].key,env[0].value)"

This would output the first key-value pair in the env array.

Functions#

Functions can be used in the property list to manipulate the data before it is printed. Functions have this format: functionName(parameter).

You can combine functions with parameters, but that might not always make sense. For example, value(count(id),id) would return something like this:

5,1234
5,5678
5,9101
5,1121
5,3141

Counting Items#

Parameters in the property list can also be functions. This can be useful for counting items. For example, to count the number of configs. You can also combine that with filters to count specific items.

Return the number of running servers:

odin fleet servers list --format="value(count(id))" --filter="status.state='running'"