Software Factory CLI

A CLI (command line interface) version of the Intent Architect Software Factory.

Why use this tool?

This tool can easily be configured as part of your CI/CD pipeline to ensure your Intent Architect design and actual solution codebase are in sync. This is analogous to ensuring your codebase compiles and all tests pass when committing code, and is one of the major benefits of a CI/CD pipeline. The intention is to extend the CI/CD pipeline checks and balances to include that all Intent Architect designs are in sync with the underlying codebase. This tool allows developers to apply the same rigor to Intent Architect changes as they do to codebase changes, ensuring a more consistent and reliable codebase. This practice is particularly important when you have a team of developers collaborating on a shared repository.

Pre-requisites

Latest release version of .NET.

Note

To take advantage of the latest performance improvements available in .NET, newer versions Intent Architect (and subsequently its Software Factory) are upgraded as soon as possible to the latest release of .NET regardless of whether it is an STS or LTS version. While Intent Architect itself ships with the runtime it requires, as the Software Factory CLI is a .NET tool, it will require that you have the latest .NET version installed.

Additional considerations when running custom modules

If your Intent Architect applications are running custom modules (i.e. modules which are not available at the https://intentarchitect.com/ repository), you will need to ensure the following:

The repository location containing your custom modules will need to be added as a repository with its Context set to Current Solution.
The operating system instance running the Software Factory CLI will need access to the location of the .imod files in order for it to be able to restore them during execution.

Tip

The Module Server can be used for self-hosting custom modules to make them available over HTTP.

Installation

This CLI tool is available as a .NET Tool and can be installed with the following command:

dotnet tool install Intent.SoftwareFactory.CLI --global

You should see output to the effect of:

You can invoke the tool using the following command: intent-cli
Tool 'intent.softwarefactory.cli' (version 'x.x.x') was successfully installed.

Common installation errors

The required NuGet feed can't be accessed, perhaps because of an Internet connection problem

If dotnet tool install fails with an error to the effect of The required NuGet feed can't be accessed, perhaps because of an Internet connection problem and it shows a private NuGet feed URL, you can try add the --ignore-failed-sources command line option (source).

The settings file in the tool's NuGet package is invalid: Settings file 'DotnetToolSetting.xml' was not found in the package

If dotnet tool install fails with an error to the effect of The settings file in the tool's NuGet package is invalid: Settings file 'DotnetToolSetting.xml' was not found in the package, this is a known misleading error by dotnet when you don't have the tool's target framework installed.

If you're seeing this error on a build server you will need to ensure it has the latest .NET SDK installed, for example on Azure Pipelines you can add the following task to the .yml file to install a version of .NET, replacing <major-version> with the major version of .NET which should be installed:

- task: UseDotNet@2
  displayName: 'Install latest .NET <major-version> SDK'
  inputs:
    version: '<major-version>.x'

This task can be used multiple times on the same Pipeline if you need to have multiple .NET SDK versions available.

Updating

A new version of the Software Factory CLI tool is also built and published as part of the automated build process which builds and publishes the Intent Architect desktop application. The version of the tool will always correspond with the version of the desktop application.

The same command for installation (dotnet tool install Intent.SoftwareFactory.CLI --global) will update the tool if an update is available and if none is available it reinstalls it making it safe to run the command as often as desired to ensure the tool is up to date.

Usage

intent-cli [command] [options]

Options

Option	Description
`-?, -h, --help`	Show help and usage information
`--version`	Show version information

Commands

Command	Description
`apply-pending-changes <username> <password> <isln-path>`	Runs the Software Factory and applies any outstanding changes.
`ensure-no-outstanding-changes <username> <password> <isln-path>`	Runs the Software Factory and if there are any outstanding changes it prints out an error and exits with a non-zero return code.

apply-pending-changes command

Runs the Software Factory and applies any outstanding changes.

apply-pending-changes usage

intent-cli apply-pending-changes <username> <password> <isln-path> [options]

apply-pending-changes arguments

Argument	Description
`<username>`	Username for an active Intent Architect account.
`<password>`	Password for the Intent Architect account. Prefix with "-- " to prevent "response file not found" errors, see https://intentarchitect.com/redirect/xwTSFCW9 for more information.
`<isln-path>`	Path to the Intent Architect solution (.isln) file or folder containing a single .isln file.

apply-pending-changes options

Option	Description
`--application-id <application-id>`	The Id of the Intent Architect application. If unspecified then all applications found in the .isln will be run.
`--attach-debugger`	The Software Factory will pause at startup giving you chance to attach a .NET debugger.
`--error-logging-command <error-logging-command>`	Command to use for logging an error. Some continuous integration environments watch output for "commands" for logging of errors. Will be automatically configured when the process is detected to be running on the following kinds of build servers: - Azure Pipelines: By default applies "{GetErrorLoggingCommand(CiType.AzurePipelines)}" (see https://learn.microsoft.com/azure/devops/pipelines/scripts/logging-commands#logissue-log-an-error-or-warning) See the documentation on Serilog.Expressions ExpressionTemplate for formatting options: https://github.com/serilog/serilog-expressions#formatting-with-expressiontemplate"\|
`--warning-logging-command <warning-logging-command>`	Command to use for logging a warning. Some continuous integration environments watch output for "commands" for logging of warnings. Will be automatically configured when the process is detected to be running on the following kinds of build servers: - Azure Pipelines: By default applies "{GetWarningLoggingCommand(CiType.AzurePipelines)}" (see https://learn.microsoft.com/azure/devops/pipelines/scripts/logging-commands#logissue-log-an-error-or-warning) See the documentation on Serilog.Expressions ExpressionTemplate for formatting options: https://github.com/serilog/serilog-expressions#formatting-with-expressiontemplate"\|
`-?, -h, --help`	Show help and usage information

ensure-no-outstanding-changes command

Runs the Software Factory and if there are any outstanding changes it prints out an error and exits with a non-zero return code.

ensure-no-outstanding-changes usage

intent-cli ensure-no-outstanding-changes <username> <password> <isln-path> [options]

ensure-no-outstanding-changes arguments

Argument	Description
`<username>`	Username for an active Intent Architect account.
`<password>`	Password for the Intent Architect account. Prefix with "-- " to prevent "response file not found" errors, see https://intentarchitect.com/redirect/xwTSFCW9 for more information.
`<isln-path>`	Path to the Intent Architect solution (.isln) file or folder containing a single .isln file.

ensure-no-outstanding-changes options

Option	Description
`--application-id <application-id>`	The Id of the Intent Architect application. If unspecified then all applications found in the .isln will be run.
`--attach-debugger`	The Software Factory will pause at startup giving you chance to attach a .NET debugger.
`--check-deviations, --check-for-unapproved-customizations`	Whether to also check for any unapproved customizations.
`--continue-on-error`	Whether Software Factory execution should continue to run for other applications when an error is encountered.
`--error-logging-command <error-logging-command>`	Command to use for logging an error. Some continuous integration environments watch output for "commands" for logging of errors. Will be automatically configured when the process is detected to be running on the following kinds of build servers: - Azure Pipelines: By default applies "{GetErrorLoggingCommand(CiType.AzurePipelines)}" (see https://learn.microsoft.com/azure/devops/pipelines/scripts/logging-commands#logissue-log-an-error-or-warning) See the documentation on Serilog.Expressions ExpressionTemplate for formatting options: https://github.com/serilog/serilog-expressions#formatting-with-expressiontemplate"\|
`--warning-logging-command <warning-logging-command>`	Command to use for logging a warning. Some continuous integration environments watch output for "commands" for logging of warnings. Will be automatically configured when the process is detected to be running on the following kinds of build servers: - Azure Pipelines: By default applies "{GetWarningLoggingCommand(CiType.AzurePipelines)}" (see https://learn.microsoft.com/azure/devops/pipelines/scripts/logging-commands#logissue-log-an-error-or-warning) See the documentation on Serilog.Expressions ExpressionTemplate for formatting options: https://github.com/serilog/serilog-expressions#formatting-with-expressiontemplate"\|
`-?, -h, --help`	Show help and usage information

FAQ

The command fails with a "Response file not found '<value>'" error

This error will show if a provided argument (typically a password) starts with an @ character and is due to it being attempted to be parsed as a response file.

To prevent an argument being interpreted as a response file it must be preceded (not necessarily immediately) by an -- argument, for example:

intent-cli ensure-no-outstanding-changes -- "user@example.com" "@Password1" "./intent-solution.isln"

Be aware that any optional arguments will need to be specified before the -- argument, for example:

intent-cli ensure-no-outstanding-changes --application-id "db9e35a9-c663-478a-93cb-ba7c0fffee43" --check-deviations -- "user@example.com" "@Password1" "./intent-solution.isln"

Example: Azure Pipelines

Tip

Install the Intent.ContinuousIntegration.AzurePipelines module into your Intent Architect application to have it automatically generate an azure-pipelines.yml file for you, refer its readme for more information.

Create a variable group with the Intent Architect account details

Create a variable group with the Intent Architect account details, for example:

Variable group with Intent Architect account details

Link the variable group to the pipeline you want to use it in

Variable groups are defined globally for an Azure DevOps project, to be able to access a variable group for a particular pipeline, it needs to be linked to it.

Add the variable group and other variables to the pipeline YAML file

To make the variable group available to a stage within your pipeline, it will need to be added to its variables. You may also want to define variables for the other command line arguments and options:

variables:
- group: 'Intent Architect Credentials'
- name: 'intentSolutionPath'
  value: 'intent'

Create a step to install the CLI

- task: PowerShell@2
  displayName: 'Install Intent Architect Software Factory CLI'
  inputs:
    targetType: 'inline'
    pwsh: true
    script: 'dotnet tool install Intent.SoftwareFactory.CLI --global'

Create a step to run the CLI

- task: PowerShell@2
  displayName: 'run intent cli'
  env:
    INTENT_USER: $(intent-architect-user)
    INTENT_PASS: $(intent-architect-password)
    INTENT_SOLUTION_PATH: $(intentSolutionPath)
  inputs:
    targetType: 'inline'
    pwsh: true
    script: |
      intent-cli ensure-no-outstanding-changes -- "$Env:INTENT_USER" "$Env:INTENT_PASS" "$Env:INTENT_SOLUTION_PATH"

A complete YAML file

trigger:
  batch: 'true'
  branches:
    include:
    - '*'

pool:
  vmImage: 'ubuntu-latest'

variables:
- group: 'Intent Architect Credentials'
- name: 'intentSolutionPath'
  value: 'intent'

steps:

- task: PowerShell@2
  displayName: 'Install Intent Architect Software Factory CLI'
  inputs:
    targetType: 'inline'
    pwsh: true
    script: 'dotnet tool install Intent.SoftwareFactory.CLI --global'

- task: PowerShell@2
  displayName: 'run intent cli'
  env:
    INTENT_USER: $(intent-architect-user)
    INTENT_PASS: $(intent-architect-password)
    INTENT_SOLUTION_PATH: $(intentSolutionPath)
  inputs:
    targetType: 'inline'
    pwsh: true
    script: |
      intent-cli ensure-no-outstanding-changes -- "$Env:INTENT_USER" "$Env:INTENT_PASS" "$Env:INTENT_SOLUTION_PATH"

Run the pipeline

When you run the pipeline, it should now install the CLI and run it.