---
title: SAIF CLI Installation
description: Install and verify the SAIF CLI, then keep your development tools and templates current.
moved_from:
  - guides/development/install-saif-cli.md
---

# SAIF CLI Installation

This guide provides step-by-step instructions for installing the SAIF CLI (Command Line Interface), a powerful tool for automating development workflows across multiple cloud services.

[TOC]

## 📚 Overview

The SAIF CLI is a console application published to a NuGet feed and installed using the .NET CLI. It provides a unified interface to automate common development tasks including:

- 🎯 Creating projects with `dotnet new` templates
- 🔄 Setting up Azure DevOps pipelines
- 📦 Creating Azure DevOps repositories
- ⚙️ Configuring project infrastructure
- 🚀 Managing deployment workflows

## ✨ Why Use SAIF CLI

The SAIF CLI provides several key benefits:

- **🎯 Single Interface**: Perform multiple operations across various cloud services from one tool
- **📏 Standardization**: Ensures all projects in CIAM are created with consistent setup and naming conventions
- **⚡ Automation**: Reduces manual work by automating repetitive development tasks
- **🔒 Best Practices**: Enforces platform standards and best practices automatically
- **⏱️ Time Savings**: Streamlines project setup and configuration processes

## 📋 Prerequisites

Before installing the SAIF CLI, ensure you have:

- ✅ Windows, macOS, or Linux operating system
- ✅ [.NET SDK](https://dotnet.microsoft.com/download) installed (see [Version Compatibility](../reference/version-compatibility.md#net) for the Forge 3.0 version)
- ✅ [Terraform](https://www.terraform.io/downloads) (for infrastructure development)
- ✅ [Node.js](https://nodejs.org/) (for TypeScript development)
- ✅ [Docker Desktop](https://www.docker.com/products/docker-desktop/) (for local development)
- ✅ [PowerShell Core (pwsh)](https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell) — required on all platforms for `saif doctor fix`
- ✅ Access to SAIF Corporation Azure DevOps organization
- ✅ Appropriate permissions to access the SAIFCorporation NuGet feed

!!! warning "Request access before you start"
    Two of these prerequisites are provisioning requests, not installs, and could take some time to be completed:

    - **Docker Desktop** requires your user to be added to the `DesktopDocker_Users` Active Directory group via a ServiceNow request. See [Docker Desktop prerequisites](../build/local-dev/index.md#prerequisites).
    - **SAIFCorporation NuGet feed access** is granted through the same request that gives you access to the SAIF Corporation Azure DevOps organization (listed above) — being added as an Azure DevOps user includes read access to the feed.

    File both requests first, then continue with the steps below while they're pending.

## 🚀 Installation Steps

Follow these steps to install the SAIF CLI on your development machine.

### Step 1: Install Azure DevOps Credential Provider

The Azure DevOps Credential Provider is required to authenticate with the SAIFCorporation NuGet feed.

#### For Windows (PowerShell)

Open PowerShell and run the following command:

```powershell
iex "& { $(irm https://aka.ms/install-artifacts-credprovider.ps1) } -AddNetfx"
```

This command will:

- Download and install the Azure Artifacts Credential Provider
- Configure it to work with .NET Framework and .NET Core
- Enable automatic authentication with Azure DevOps feeds

#### For macOS/Linux (Bash)

Open a terminal and run:

```bash
sh -c "$(curl -fsSL https://aka.ms/install-artifacts-credprovider.sh)"
```

### Step 2: Add SAIFCorporation NuGet Source

Add the SAIFCorporation NuGet feed as a package source:

```bash
dotnet nuget add source https://pkgs.dev.azure.com/SAIFCorporation/_packaging/SAIFCorporation/nuget/v3/index.json -n SAIFCorporation
```

**What this does:**

- Registers the SAIFCorporation NuGet feed with your .NET CLI
- Names the source "SAIFCorporation" for easy reference
- Enables access to SAIF platform packages and tools

If the source already exists, `dotnet nuget add source` fails. Skip this step, or point the existing source at the feed:

```bash
dotnet nuget update source SAIFCorporation --source https://pkgs.dev.azure.com/SAIFCorporation/_packaging/SAIFCorporation/nuget/v3/index.json
```

### Step 3: Install SAIF CLI

Install the SAIF CLI as a global .NET tool:

```bash
dotnet tool update --global SAIF.Platform.CLI
```

**Command explanation:**

- `dotnet tool update --global`: Installs or updates a global .NET tool
- `SAIF.Platform.CLI`: The package name for the SAIF CLI
- Using `update` instead of `install` ensures you get the latest version, even if already installed

**Expected output:**

```text
Tool 'saif' (version '<latest version>') was successfully installed.
```

### Step 4: Install Platform Packages and Templates

After installing the CLI, run `saif doctor fix` to download all the latest packages, tools, and SAIF templates for platform development:

```bash
saif doctor fix
```

## ✅ Verify Installation

After installation, verify that the SAIF CLI is correctly installed and accessible.

### Check SAIF CLI Version

Run the following command:

```bash
saif --version
```

**Expected output:**

You should see the version number of the installed SAIF CLI, such as:

```text
1.2.3
```

### Test SAIF CLI Help

Display the available commands:

```bash
saif --help
```

This will show a list of available commands and options, confirming the CLI is working correctly.

## 🔄 Updating SAIF CLI

The `saif update` command has been deprecated. Use `saif doctor fix` to update tools and templates, or `saif doctor fix --self` to update the CLI binary itself.

### Update tools and templates

To update all platform tools and templates (recommended for most cases):

```bash
saif doctor fix
```

This command will:

- Diagnose your environment for outdated or missing tools and templates
- Apply fixes for everything that needs updating
- Report what was changed and what is already healthy

!!! note "Aspire CLI install method migration"
    If you previously installed Aspire CLI as the `Aspire.Cli` .NET global tool, `saif doctor fix`
    automatically uninstalls that copy and reinstalls Aspire via the official installer at
    `https://aspire.dev/install.ps1`. This converges machines on the binary install path that
    supports `aspire update --self`. Aspire CLI 13.4+ requires `--yes` alongside `--non-interactive`
    for the underlying `aspire update --self` command, so `saif doctor fix` tries that form first
    and automatically retries without `--yes` for older, pre-13.4 installs.

### Update Forge Agent Plugins

See [Keeping Forge plugins up to date](forge-plugin.md#keeping-packages-up-to-date) for plugin-only updates, registration repair, and recovery from a failed refresh.

### Update the SAIF CLI binary itself

Self-update is opt-in and handled separately:

```bash
saif doctor fix --self
```

`saif doctor fix --self` starts a background PowerShell Core process that waits for the current `saif` process to exit and then runs `dotnet tool update --global SAIF.Platform.CLI`, the same command as [Step 3](#step-3-install-saif-cli). It reports that the update was initiated before the new binary is on disk, so wait for the background update to finish (the [update-everything sequence](#update-everything) pauses 20 seconds) before you run `saif --version` or another `saif` command. If PowerShell Core isn't installed, the self-update can't start; run the [Step 3 command](#step-3-install-saif-cli) directly instead.

### Update everything

To update the CLI, tools, and templates together, run the self-update first so the updated CLI applies the remaining fixes:

```powershell
saif doctor fix --self
Start-Sleep -Seconds 20  # The CLI update runs in the background after saif exits
saif doctor fix
```

`saif doctor fix` itself runs in the foreground and needs no pause afterward. It installs Aspire CLI through a child PowerShell process, so if it installed Aspire or migrated it from the .NET tool, open a new terminal (and restart VS Code) so the updated `PATH` loads.

### Preview updates without applying

To see what would be updated without making changes:

```bash
saif doctor fix --dry-run
```

### Check for Updates

To see if an update is available without installing:

```bash
dotnet tool list --global
```

This shows all installed global tools and their current versions.

## 🔍 Troubleshooting

### ❌ Common Issues and Solutions

#### Issue: "Unable to load the service index for source"

**Solution**: Ensure you have access to the SAIFCorporation Azure DevOps organization and the credential provider is installed correctly.

```bash
# Reinstall the credential provider
iex "& { $(irm https://aka.ms/install-artifacts-credprovider.ps1) } -AddNetfx"

# Clear NuGet cache
dotnet nuget locals all --clear
```

#### Issue: "Tool 'saif' is not recognized"

**Solutions**:

- ✅ Ensure the .NET tools path is in your system PATH environment variable
- ✅ Close and reopen your terminal/PowerShell window
- ✅ Verify installation with `dotnet tool list --global`

**Windows PATH location:**

```text
%USERPROFILE%\.dotnet\tools
```

**macOS/Linux PATH location:**

```text
$HOME/.dotnet/tools
```

#### Issue: Authentication fails when installing

**Solutions**:

- ✅ Ensure you're logged into Azure DevOps in your browser
- ✅ Run the credential provider installation again
- ✅ Try clearing cached credentials:

```bash
# Windows
cmdkey /delete:https://pkgs.dev.azure.com/SAIFCorporation

# macOS/Linux
rm -rf ~/.nuget/plugins/netcore
```

#### Issue: "A newer version of this tool already exists"

**Solution**: Use `update` instead of `install`, as in the [Step 3 install command](#step-3-install-saif-cli).

#### Issue: Package source already exists

**Solution**: Skip the add step, or update the existing source as described in [Step 2](#step-2-add-saifcorporation-nuget-source).

### 🔧 Debugging Tips

#### Enable Detailed Logging

For more detailed error messages, set verbose logging:

```bash
$env:DOTNET_CLI_CONTEXT_VERBOSE="true"
saif --version
```

#### Check Installed Tools

List all globally installed .NET tools:

```bash
dotnet tool list --global
```

#### Verify NuGet Sources

List all configured NuGet sources:

```bash
dotnet nuget list source
```

## 🤖 AI Assistant Integration

<a id="install-the-forge-plugin-packages"></a>
<a id="azure-operations-are-intentionally-out-of-scope"></a>

After verifying `saif --version`, follow [Set up Forge Agent Plugins](forge-plugin.md) for package selection, configuration scope, verification, and optional shell permissions. Its [installation steps](forge-plugin.md#install-the-forge-plugin-packages) cover automatic setup and the optional planning package, and the [plugin package boundary](forge-plugin.md#azure-operations-are-intentionally-out-of-scope) explains why Azure operations are out of scope.

## 📖 Next Steps

Now that you have the SAIF CLI installed, run `saif --help` to list the commands, then create your first project in [Your First Forge Application](tutorials/index.md). The [generated command reference](../reference/dotnet/SAIF.Platform.CLI/commands.md) documents every command and option, and [`saif docs search`](../reference/cli-workflows.md#saif-docs-search) finds Forge guidance without leaving your terminal.

## 📚 Related Documentation

- [Your First Forge Application](tutorials/index.md) - Create a project using SAIF CLI
- [Project Templates](project-templates.md) - Available templates for new projects
- [Deployment](../build/deploy/index.md) - Azure DevOps integration
- [Version Compatibility](../reference/version-compatibility.md) - Supported .NET versions

## 📖 Additional Resources

- [Azure DevOps Credential Provider](https://github.com/microsoft/artifacts-credprovider)
- [.NET Global Tools Documentation](https://learn.microsoft.com/en-us/dotnet/core/tools/global-tools)
- [SAIF Platform Documentation](../index.md)

---

Happy automating with SAIF CLI! 🎉