Command line interface

cirocket is a command line application and can be run in any shell or Windows terminal.

The basic usage is

cirocket [command]

The following commands are supported by cirocket:

Command Function
assemble assemble a mission from a blueprint
completion generate the autocompletion script for the specified shell
help Help about any command
init init a new mission or runbook
launch launch the cirocket
list list lists resources (types: blueprints, tasktypes)
version Detailed version information

All commands support the the global flags:-

Flag Function
config path to the configuration file too use. If the flag is not specified the default location ~/.cirocket/config.yml is used.
debug indicates additional debugging information should be output in the logs.
dir sets the working directory prior to running the command.
-h, --help help for cirocket
silent silence output (ignored if debug is specified too) Reduces the amount of output that is logged.

assemble

The assemble command is used to execute a mission defined in a blueprint. Blueprints are packaged cirocket missions that are stored in blueprint repositories. Blueprint missions are often used to create or setup new development projects. A blueprint mission will create local resources using templated configuration. The specific template values are often provided to the assembly command iin the form of a run book config file. The init runbook command can be used to create a default run book for any blueprint.

The assemble command:-

cirocket assemble [blueprint] [flags]

The argument blueprint is the name of a blueprint. To see available blueprint names run cirocket list blueprints.

Flag Function
param name=value Multiple input param flags can be specified. Each flag provides a param name(key) and value pair. These are passed into the mission.
Command line parameters provide a default value, if a mission sets aan alternative value for the same key it will be used in place of the passed command line option. This is done to follow the cirocket convention of allowing child entities to override default values provided by their parent.
If you would prefer a passed value to override a child value the child should define its value using a template similar to {{ or .paramKey “default” }}. This way if an existing paramKey exists its value will be used in place of the child’s default.
runbook pathToRunbook A single optional --runbook flag can be provided along with a path to the runbook. The path may be relatiive to teh current working directory, a http(s) or file URL or an absolute path. The runbook is a yaml file containing a list of default parameter values. Note --param values take residence over runbook values. The advantage of using the runbook is all the values are contained ina single file and can reference both inline and remote values.

completion

The completion command generates shell completion scripts for the cirocket commands.

cirocket completion [shell]

Supported shells include:

  • Bash:
  $ source <(cirocket completion bash)

  # To load completions for each session, execute once:
  # Linux:
  $ cirocket completion bash > /etc/bash_completion.d/cirocket
  # macOS:
  $ cirocket completion bash > /usr/local/etc/bash_completion.d/cirocket
  • Zsh:
  # If shell completion is not already enabled in your environment,
  # you will need to enable it.  You can execute the following once:

  $ echo "autoload -U compinit; compinit" >> ~/.zshrc

  # To load completions for each session, execute once:
  $ cirocket completion zsh > "${fpath[1]}/_cirocket"

  # You will need to start a new shell for this setup to take effect.
  • Fish:
  $ cirocket completion fish | source

  # To load completions for each session, execute once:
  $ cirocket completion fish > ~/.config/fish/completions/cirocket.fish
  • PowerShell:
  PS> cirocket completion powershell | Out-String | Invoke-Expression

  # To load completions for every new session, run:
  PS> cirocket completion powershell > cirocket.ps1
  # and source this file from your PowerShell profile.

help

The help command provides basic help about each command.

cirocket help [command]

For example to get help on the assemble command run

cirocket help assemble

You can alternatively get the same help on any command by including either the -h or --help flag.

## init

The init command is used to create a new mission or runbook file.

mission

cirocket init mission [--mission filename]

The init mission command creates a new boilerplate mission file. If --mission filename is specified the new file will be created using the filename. If no flag is provided the default filename .cirocket.yml will be used. If the file already exists an error will be returned.

runbook

cirocket init runbook [blueprint]

The init runbook command creates a new boilerplate runbook parameter file for the specified blueprint. The command attempts to locate the blueprint using the pre-configured blueprint search locations. If it is found, a copy of the blueprint’s runbook will be created locally.

launch

cirocket launch [sequence] [--mission filename]

The launch command runs a mission. The flag --mission can be used to specify the mission file. If it is not provided the default file .cirocket.yml will be used. If the file does not exist and error will be returned.

Multiple sequence arguments can be listed. Missions that don’t define sequences run all the mission stages defined in the mission in the order they are specified in the file. These missions will error if sequences are provided. Missions however that define sequences require at least one sequence name to b specified. If multiple sequence names are provided the mission will execute the mission in the order specified by the sequences reading left to right.

list

The list command is used to list information on a specific entity type. Currently 2 entities are supported:

  • blueprints - list all blueprints held in the configured blue print registries.
  • tasktypes - list all the available types of tasks supported.

The list command supports flexible output reporting including text, grid, markdown, csv, json and yaml output formats.

Format flags

The following format flags are supported

Flag Function
format Specifies the output format.
Supported formats include:
- csv – basic delimited list
- json
- yaml
- text (default)
- template – used to render output using a go template
style Used with text format only:
Specifies the text output style.
Options include:
- plain – raw text output, columns ar separated by spaces or --separator string
- grid – draws a text grid around the output columns, column text will word wrap as required.
- aligned – similar to the grid output but without a border drawn.
- md – a basic markdown table is output.
ttywidth Used with text format only:
When a grid is drawn the width of the terminal is used to calculate the column widths. In most cases this is automatically calculated by the program. If however a explicit terminal width is required this flag can be used. The width is measured in characters.
jsonindent Used with json format only:
Specifies the number of spaces to indent nested elements. The default is 2 spaces.
separator Used with csv and text/plain formats only:
Specifies the separator character to use between columns,
template Used with template format only:
Allows an inline Go template to be used in place of an output format.
templatefile Used with template format only:
Renders the text using a Go template in the specified file.
colset This is an optional comma separated list of columns to include in the output. If specified only columns in this list will be output.
excludecols An optional list of columns to exclude from the output set.

blueprints

cirocket list blueprints [outputflags]

For templated output the dot data element is a slice (array) of BlueprintInfo.

tasktypes

cirocket list tasktypes [outputflags]

For templated output the dot data element is a slice (array) of TaskTypeInfo.

version

cirocket version

The version command provides detailed version information on the installed cirocket executable.

The current version can also be obtained using

cirocket -v