# 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 (version 10.0 for Forge 3.0)
- ✅ [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

## 🚀 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

### 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

### Update the SAIF CLI binary itself

Self-update is opt-in and handled separately:

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

### Preview updates without applying

To see what would be updated without making changes:

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

### Alternative Method

You can also update the CLI binary directly using the .NET tool command:

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

### 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 the `update` command instead of `install`:

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

#### Issue: Package source already exists

**Solution**: If the NuGet source is already added, you'll see an error. You can either:

1. Skip this step, or
2. Update the existing source:

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

### 🔧 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
```

## 📖 Next Steps

Now that you have the SAIF CLI installed, explore these resources:

- 📘 **View available commands**: Run `saif --help` to see all available commands
- 🚀 **Create your first project**: Use `saif new` to scaffold a new application
- 🔧 **Configure your environment**: Set up additional tools and credentials
- 📖 **Explore documentation**: Visit [Forge Documentation](https://dev.azure.com/SAIFCorporation/Platform/_git/forge?path=/docs) for detailed guides

### Common SAIF CLI Commands

Here are some frequently used commands to get you started:

```bash
# View CLI version
saif --version

# Show help for all commands
saif --help

# Show help for a specific command
saif <command> --help

# View available templates
saif new --help

# Create a new project from template (prompted for options)
saif new <template-name>

# Update tools and templates
saif doctor fix

# Update the SAIF CLI binary itself
saif doctor fix --self
```

## 📚 Related Documentation

- [Your First Forge Application](../tutorials/index.md) - Create a project using SAIF CLI
- [Project Templates](../../reference/tools/project-templates.md) - Available templates for new projects
- [Azure DevOps Services](../../reference/tools/azure-devops-services.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! 🎉