Archy Commands and Parameter Values

Similar to other command line tools, you can get a listing of available commands by accessing help at the command line:

> archy --help

To get help on an individual command, you run the command with the --help option. For example, if we wanted to get help on the refresh command, we would run this at the command line:

> archy refresh --help

When you get help on an individual command, the help will contain information about the supported parameters as well.

Similar to other command line tools, Archy supports supplying values to commands with command line parameters. Many commands also accept an options file. The options file is a YAML file where you specify a command line parameter and the value you wish to use. Then when running the Archy command instead of passing in a command line parameter and value, you specify the options file that will supply values.

We encourage use of options files. They provide a really nice mechanism to encapsulate parameter values which can be very handy for scenarios where you want to perform operations against one organization, then the same set of operations against another org, etc. etc. In automation pipelines, they are also handy to supply values for different environments as well.

Here's a quick example. We could run an archy publish command like this:

archy publish --file myFlow.yaml --clientId xxx --clientSecret yyy

If you created an myOptions.yaml file that looks like this:

clientId: xxx
clientSecret: yyy

You could then run the archy publish with the following:

archy publish --optionsFile myOptions.yaml --file myFlow.yaml

And yes, we could have put the flow YAML file in the options file too if we wanted. While it's not part of this article, options files also are where you specify substitution key / value pairs that will be processed by Archy as well.

So here is how Archy works when it is looking to get the value of a parameter when running a command. It's a simple hierarchy but shows why we have you set up default setting values with the archy setup or archy configure command:

1. Command Line Parameter - if when running a command and there is a value for a parameter supplied on the command line, that value is what will be used by the command.
2. Options File - if no value for a parameter is specified on the command line but is present as a key in the root of an options file, that value will be used. Processing an options file only happens if a --optionsFile parameter is supplied on the command line.
3. Default Setting Values - if there is no command line parameter and either no options file specified or the options file does not have the parameter value supplied, Archy will then look to see if the value is defined in the default settings. These values are set when someone runs the archy setup command at the beginning or runs the archy configure command.

One nice thing is that when you run an Archy command, one of the very first things it will write out is the values it is using for command parameters and where it got the value from.

For example, almost all Archy commands have a debug command line parameter that enables additional diagnostic output. If you specify --debug true as a command line parameter, Archy will use that value. Next, if the command accepts an optionsFile parameter and you specified --optionsFile ~/archy/archyHome/dev/options.yaml then Archy would look for a debug key in the options YAML file and use that. Finally, if there is no options file specified or the options file doesn't have a debug key and the value one is store in the Archy configuration, Archy will look for the value there.

When you run a command, one nice thing that Archy does is it outputs the parameter values being used for the command and where it got the value. Here is example output on an archy publish command:

****************************************************************************************************
                       Runtime Configuration
****************************************************************************************************

authToken:     ''
               source - undefined

clientId:      '<this would be the real client id value that is being used>'
               source - options file: '/Users/john.smith/archy/automation/archy-tests/src/optionsFiles/optionsFileCommon.yaml'

clientSecret:  '<this would be the real client secret value that is being used>'
               source - options file: '/Users/john.smith/archy/automation/archy-tests/src/optionsFiles/optionsFileCommon.yaml'

debug:         true
               source - command line parameter

file:          '/Users/john.smith/archy/automation/archy-tests/src/flowYamlFiles/basicFlow.yaml'
               source - command line parameter

forceUnlock:   false
               source - default value

location:      'prod_us_east_1'
               source - options file: '/Users/john.smith/archy/automation/archy-tests/src/optionsFiles/optionsFileCommon.yaml'

optionsFile:   '/Users/john.smith/archy/automation/archy-tests/src/optionsFiles/optionsFileCommon.yaml'

recreate:      'false'
               source - default value

If you want to see the default configuration setting values currently configured, you can do this with the following command:

archy dump

And if you want to set values, such as the default client id / secret you wish to use when running Archy commands, you can do this by running the following:

archy configure

You can also run archy setup because setting up Archy default setting values is part of the overall setup process. The thing to remember is that supplying Archy default setting values is one part of the setup process which does more stuff as well.

This behavior is nice because if you set up the client id / secret in the Archy configuration, you can run Archy commands and not have to specify values each time you run the command since Archy will fall back and use the value in the configuration.

Archy - Ver. 2.33.1, generated on January 3, 2025