Skip to main content

Output formatting

Output formatting

By default, the result of 'computesphere' commands are output in line-based plain text. Some commands support additional output formats, such as JSON, YAML, and CSV. The output format can be set using the '--output' flag.

  • table: A table format that displays data in tables. Default format.
  • plain: A plain text format that displays data in a plain text format, delimited by tabs. Useful for piping.
  • json: A JSON format that displays data in JSON format.
  • yaml: A YAML format that displays data in YAML format.
  • csv: A CSV format that displays data in CSV format. CLI will remember the output setting for future commands.

Once in JSON, the output can be further formatted using '--fields', '--jq', and '--template' flags. This allows you to filter, transform, and format the output to suit your needs.

--fields Allows you to select specific fields to display. It requires a comma-separated list of field names. To view the possible fields for a command omit the argument and the CLI will display the available fields.

--jq Allows you to use jq filters to transform the JSON output. It requires a valid jq filter string. To learn more about jq, visit [https://jqlang.github.io/jq]. Query can be used to select, elements from an array, fields from an object, create a new array, and more. The 'jq' utility does not need to be installed on your system, as the CLI uses a built-in jq processor. jq queries can be complex, so it is possible to use the '--fields' flag to reduce the output before using jq.

--template Allows you to use Go templates to format the JSON output. It requires a valid Go template string. To learn more about Go templates, visit [https://golang.org/pkg/text/template]. In addition to the standard Go template functions, the CLI provides additional functions for coloring and table rendering.

  • color [color] [input] : colorize the input using [https://github.com/mgutz/ansi].
  • autocolor [color] [input] : the same as above, but only emits color to terminals.
  • join [sep] [list] : join a list of strings with a separator.
  • pluck [field] [list] : collects values of a field from all items in the output.
  • tablerow [fields]... : aligns fields in output vertically as a table.
  • tablerender : renders fields added by 'tablerow' in place.
  • timeago [time] : renders a timestamp as relative to now.
  • timefmt [format] [time] : formats a timestamp using a Go time format function 'Time.Format'.
  • truncate [length] [input] : truncates the input to a maximum length.
  • hyperlink [url] [text] : creates a hyperlink.

Examples​

# default output format
$ csph environment list

# adding the '--output' flag to output in JSON format
$ csph environment list --output json

# using the '--fields' flag to select specific fields
$ csph environment list \
     --output json \
     --fields id,name

# using the '--jq' flag to transform the JSON output
$ csph environment list \
     --output json \
     --jq '.[] | {identifier: .id, environment: .name}'

# using the '--fields' flag to select specific fields
# and the '--jq' flag to transform the JSON output
$ csph environment list \
     --output json \
     --fields id,name
     --jq '.[] | {identifier: .id, environment: .name}'

# using the '--fields' flag to select specific fields
# and the '--template' flag to format the JSON output
$ csph environment list \
     --output json \
     --fields id,name \
     --template '{{range .}}{{.id}} -> {{.name}}{{"\n"}}{{end}}'

# adding the '--template' flag to modify the display format and add some colors
$ csph environment list \
     --output json \
     --fields id,name \
     --template '{{range .}}{{.id | color "green"}} -> {{.name | color "blue"}}{{"\n"}}{{end}}'

# using the '--fields' to select specific fields
# and the '--template' flag to format the JSON output with a table
$ csph environment list \
     --output json \
     --fields id,name,created_at \
     --template '{{tablerow "ID" "Name" "Created"}}{{range .}}{{tablerow .id .name (timeago .created_at)}}{{end}}{{tablerender}}'

See also​