= Runtime Configuration

Configuration for the CLI can be performed in several ways:

- On the command line
- Using environment variables
- Using a configuration file (YAML or JSON)

When using a configuration file, it is possible to set up more than one project.

== Settings

The following tables show the configuration options that are available at the root level and the command level.

=== Global Options

The following options can be applied to any command within the Ensono Stacks CLI.

[cols="a,a,a,a,a",stripes=even]
|===
| Option | Environment Variable | Description | Default | Options

| `-c`, `--config` | ENSONOSTACKS_CONFIG | Path to the configuration file to use | | 
| `-l`, `--loglevel` | ENSONOSTACKS_LOG_LEVEL | Level of logging to be used | `info` | `debug`, `info`, `warning`, `error`, `fatal`
| `-f`, `--logformat` | ENSONOSTACKS_LOG_FORMAT | Output type of the logging | `text` | `text`, `json`
| `--logcolour` | ENSONOSTACKS_LOG_COLOUR | State if logging should include color | | 
| `--logfile` | ENSONOSTACKS_LOG_FILE | Write all logs to the specified file | | 
| `-w`, `--workingdirectory` | ENSONOSTACKS_DIRECTORY_WORKINGDIR | Directory that the projects should be created in | `${PWD}` |
| `--tempdir` | ENSONOSTACKS_DIRECTORY_TEMPDIR | Directory to be used by Ensono Stacks for its temp files | System temp directory |
| `--nobanner` | ENSONOSTACKS_OPTIONS_NOBANNER | Do not display the Ensono Stacks banner when running the command | `false` |
| `--nocliversion` | ENSONOSTACKS_OPTIONS_NOCLIVERSION | Do not perform a version check for the latest version of the Ensono Stacks CLI | `false` |
|===

Global Options

=== Scaffold Options

[cols="a,a,a,a,a",stripes=even]
|===
| Option | Environment Variable | Description | Default | Options

| `-n`, `--name` | ENSONOSTACKS_PROJECT_NAME | Name of the project to create | | 
| `--sourcecontrol` | ENSONOSTACKS_PROJECT_SOURCECONTROL_TYPE | Source control system to be used | `github` | 
| `-u`, `--sourcecontrolurl` | ENSONOSTACKS_PROJECT_SOURCECONTROL_URL | URL to the remote repository | | 
| `--projectsettingsfile` | ENSONOSTACKS_PROJECT_SETTINGSFILE | Each project will have its own `stackscli.yml` file, however, this can be overridden with a path to a different file using this option | `null` | 
| `-F`, `--framework` | ENSONOSTACKS_PROJECT_FRAMEWORK_TYPE | The framework that is to be used | | `dotnet`, `java`, `nx`
| `-O`, `--frameworkoption` | ENSONOSTACKS_PROJECT_FRAMEWORK_OPTION | The sort of project to be created | | `webapi`, `cqrs`, `events`
| `-V`, `--frameworkversion` | ENSONOSTACKS_PROJECT_FRAMEWORK_VERSION | The version of the Ensono Stacks project to use. This can be a version, a tag, a SHA ref, or a branch. | `latest` | 
| `--frameworkprop1` | ENSONOSTACKS_PROJECT_FRAMEWORK_PROPERTIES_PROP1 | Properties that need to be set to allow the scaffolding to run the correct command. The project settings file will be defined by the project maintainers but may specify that a property needs to be set. | | 
| `--frameworkprop2` | ENSONOSTACKS_PROJECT_FRAMEWORK_PROPERTIES_PROP2 | | | 
| `--frameworkprop3` | ENSONOSTACKS_PROJECT_FRAMEWORK_PROPERTIES_PROP3 | | | 
| `--frameworkprop4` | ENSONOSTACKS_PROJECT_FRAMEWORK_PROPERTIES_PROP5 | | | 
| `--frameworkprop5` | ENSONOSTACKS_PROJECT_FRAMEWORK_PROPERTIES_PROP5 | | | 
| `-P`, `--platformtype` | ENSONOSTACKS_PLATFORM_TYPE | Platform being deployed to | | `aks`
| `-p`, `--pipeline` | ENSONOSTACKS_PIPELINE | Pipeline being used to build the project | | `azdo`
| `-C`, `--cloud` | ENSONOSTACKS_CLOUD | Cloud platform being used | | `azure`, `aws`, `gcp`
| `-R`, `--cloudregion` | ENSONOSTACKS_CLOUD_REGION | Region that the project will be deployed to | | 
| `-G`, `--cloudgroup` | ENSONOSTACKS_CLOUD_GROUP | Group in the cloud platform that will hold all the resources | | 
| `--company` | ENSONOSTACKS_BUSINESS_COMPANY | Name of your company or organization | | 
| `-A`, `--area` | ENSONOSTACKS_BUSINESS_DOMAIN | Area of the company that is responsible for the project | | 
| `--component` | ENSONOSTACKS_BUSINESS_COMPONENT | Component of the overall project | | 
| `--tfstorage` | ENSONOSTACKS_TERRAFORM_BACKEND_STORAGE | Name of the storage account being used for the state | | 
| `--tfgroup` | ENSONOSTACKS_TERRAFORM_BACKEND_GROUP | Group name of the storage account | | 
| `--tfcontainer` | ENSONOSTACKS_TERRAFORM_BACKEND_CONTAINER | Container being used to store the data | | 
| `-d`, `--domain` | ENSONOSTACKS_NETWORK_BASE_DOMAIN_EXTERNAL | External domain root to be used for the projects | | 
| `--internaldomain` | ENSONOSTACKS_NETWORK_BASE_DOMAIN_INTERNAL | Internal domain root to be used for projects. If not specified, then the internal domain will be inferred from the external by replacing the TLD with `internal`. Thus if `mydomain.com` is provided as the external domain, then the internal will be set to `mydomain.internal`. | | 
| `--cmdlog` | ENSONOSTACKS_OPTIONS_CMDLOG | Create a log file of all the commands that have been run during the scaffold process. The command log is created in the current directory with the filename `cmdlog.txt`. | `false` | 
| `--dryrun` | ENSONOSTACKS_OPTIONS_DRYRUN | Perform a dry run of the scaffold process. Useful for checking that things will be set up as required. No operations will be performed on the machine when run in this mode. | `false` | 
| `--settingsfile` | ENSONOSTACKS_SETTINGSFILE | Name of the file to look for in the project | `stackscli.yml` | 
| `--cmdlog` | ENSONOSTACKS_CMDLOG | Generate a log of all the commands that the CLI has run. The `cmdlog.txt` file is created in the directory that the CLI has been run in. | `false` | 
| `--dryrun` | ENSONOSTACKS_DRYRUN | Perform a dry run of all the CLI. Particularly useful when used with `--cmdlog`. | `false` | 
| `--save` | ENSONOSTACKS_SAVE | If using the interactive or command-line mode for configuring the CLI, the given configuration can be saved to a file. This allows the configuration to be replayed again at a later date. The configuration is saved to `stacks.yml` in the specified working directory. | `false` | 
| `--nocleanup` | ENSONOSTACKS_NOCLEANUP | Do not perform cleanup operations after the scaffolding has been completed. | `false` | 
| `--force` | ENSONOSTACKS_FORCE | *This is a destructive operation* By using `force`, the CLI will delete any projects of the same name that already exist in the working directory and then create the new project in its place. It will also continue to run if the command version checks fail. For example, if the project calls for `dotnet` version 3.1 and you have 5.0.303, the CLI would not normally continue, but with `force`, this will be ignored, and the process will continue. | `false` | 
|===

== Command Log Format

If the command log has been enabled, using `--cmdlog`, a file with all the commands that have been run during the scaffolding operation will be generated. The format of this file is as follows:

`[<DIR>] <CMD> <ARGS>`

The `<DIR>` shows in which directory the command has been run. Please note that this directory may have been deleted after the CLI has been run as it was temporary.

The `<CMD>` and `<ARGS>` show the command that was run and the arguments that were passed to it.

NOTE: On Windows-based machines, the `<CMD>` will be prefixed with `cmd /C`, which tells the CLI how to run the command. PowerShell has not yet been used as it is easy to customize the shell, and those customizations may cause the CLI to fail when running the commands.

== Configuration File

The following shows an example of a configuration file that can be passed to the command.

.CLI Configuration File.
[source,yaml]
----
project:
  - name: tigerfest
    framework:
      option: webapi
      version: latest
    platform:
      type: aks
    sourcecontrol:
      type: github
      url: https://github.com/russellseymour/my-new-project.git

pipeline: azdo

cloud:
  platform: azure
  region: ukwest
  group: a-new-resource-group

business:
  company: MyCompany
  domain: core
  component: infra

terraform:
  backend:
    storage: adfsdafsdfsdf
    group: Stacks-Ancillary-Resources
    container: tfstate

network:
  base:
    domain:
      external: mydomain.com

log:
  level: info

options:
  cmdlog: false
  dryrun: false

stacks:
  dotnet:
    webapi:
      url: https://github.com/Ensono/stacks-dotnet
      trunk: master
----

Note that when using the configuration file, it is possible to specify multiple projects to be configured. This allows several projects to be set up at the same time, without having to run the command multiple times. Each project will be created within the specified working directory.

If this file was called `conf.yml`, the command to run to consume the file would be:

----
.\stacks-cli.exe scaffold -c .\local\conf.yml
----



