Config Settings

The ICA CLI accepts configuration settings from multiple places, such as environment variables, configuration file, or passed in as command line arguments. When configuration settings are retrieved, the following precedence is used to determine which setting to apply:

  1. Command line options - Passed in with the command such as --access-token

  2. Environment variables - Stored in system environment variables such as ICAV2_ACCESS_TOKEN

  3. Default config file - Stored by default in the ~/.icav2/config.yaml on macOS/Linux and C:\Users\USERNAME\.icav2\.config on Windows

Command Line Options

The following global flags are available in the CLI interface:

-t, --access-token string    JWT used to call rest service
-h, --help                   help for icav2
-o, --output-format string   output format (default "table")
-s, --server-url string      server url to direct commands
-k, --x-api-key string       api key used to call rest service

Environment Variables

Environment variables provide another way to specify configuration settings. Variable names align with the command line options with the following modifications:

  • Upper cased

  • Prefix ICAV2_

  • All dashes replaced by underscore

For example, the corresponding environment variable name for the --access-token flag is ICAV2_ACCESS_TOKEN.

Disable Retry Mechanism

The environment variable ICAV2_ICA_NO_RETRY_RATE_LIMITING allows to disable the retry mechanism. When it is set to 1, no retries are performed. For any other value, http code 429 will result in 4 retry attempts:

  • after 500 milliseconds

  • after 2 seconds

  • after 10 seconds

  • after 30 seconds

Config File

Upon launching icav2 for the first time, the configuration yaml file is created and the default config settings are set. Enter an alternative server URL or press enter to leave it as the default. Then enter your API Key and press enter.

After installing the CLI, open a terminal window and enter the icav2 command. This will initialize a default configuration file in the home directory at .icav2/config.yaml.

To reset the configuration, use ./icav2 config reset

Resetting the configuration removes the configuration from the host device and cannot be undone. The configuration needs to be recreated.

Configuration settings is stored in the default configuration file:

access-token: ""
colormode: none
output-format: table
server-url: ica.illumina.com
x-api-key: !!binary SMWV6dEXAMPLE

The file ~/.icav2/.session.ica.yamlon macOS/Linux and C:\Users\USERNAME\.icav2\.session.ica on Windows will contain the access-token and project-id. These are output files and should not be edited as they are automatically updated.

Examples

ICAV2_X_API_KEY

This variable is used to set the API Key.

  1. Command line options - Passed as --x-api-key <your_api_key> or -k <your_api_key>

  2. Environment variables - Stored in system as ICAV2_X_API_KEY

  3. Default config file - Use icav2 config set to update ~/.icav2/config.yaml(macOS/Linux) or C:\Users\USERNAME\.icav2\.config (Windows)

Last updated