Skip to content

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.

On this page

📚 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 installed (version 10.0 for Forge 3.0)
  • ✅ Terraform (for infrastructure development)
  • ✅ Node.js (for TypeScript development)
  • ✅ Docker Desktop (for local development)
  • ✅ PowerShell Core (pwsh) — required on all platforms for saif doctor fix
  • ✅ Access to SAIF Corporation Azure DevOps organization
  • ✅ Appropriate permissions to access the SAIFCorporation NuGet feed

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.
  • 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:

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:

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:

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:

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:

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:

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:

saif --version

Expected output:

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

1.2.3

Test SAIF CLI Help

Display the available commands:

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):

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 Forge Agent Plugins

saif doctor / saif doctor fix (with no filter flags) also covers the Forge Agent Plugins registered by saif agent init: it detects plugins that are missing, out of date, or not correctly registered in Copilot's settings.json and VS Code's chat.plugins.marketplaces, and doctor fix repairs them the same way agent init would. Target just that group with --agent:

saif doctor fix --agent

Note

Version-drift detection compares each installed plugin's plugin.json version against the same field in the saif-corp/forge marketplace. It only flags real drift once plugin releases start bumping that version; a missing install or a stale registration is always caught regardless.

Update the SAIF CLI binary itself

Self-update is opt-in and handled separately:

saif doctor fix --self

Preview updates without applying

To see what would be updated without making changes:

saif doctor fix --dry-run

Alternative Method

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

dotnet tool update --global SAIF.Platform.CLI

Check for Updates

To see if an update is available without installing:

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.

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

%USERPROFILE%\.dotnet\tools

macOS/Linux PATH location:

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

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

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

Check Installed Tools

List all globally installed .NET tools:

dotnet tool list --global

Verify NuGet Sources

List all configured NuGet sources:

dotnet nuget list source

🤖 AI Assistant Integration

If you use VS Code or GitHub Copilot CLI, register the Forge Agent Plugins so agents can look up saif commands and documentation without shelling out:

Install saif first and verify it before you install Forge plugins

.github/plugins/forge/mcp.json registers the Forge MCP server with "command": "saif", which is a bare executable token, not an absolute path. Agent Plugins spec §7.2.1 allows only a bare executable name or a plugin-relative ./... path, and says conformant plugins must not depend on client-configured PATH behavior for bare commands. That means the Forge plugin cannot bootstrap the SAIF CLI for you. Install the CLI first, make sure saif is already on your PATH, and verify it with saif --version before you install or activate forge or forge-planning.

saif agent init

This detects installed hosts and writes declarative plugin registration automatically. By default it:

  • writes ~/.copilot/settings.json (or $COPILOT_HOME/settings.json) with Forge's extraKnownMarketplaces entry plus enabledPlugins
  • appends saif-corp/forge to each detected VS Code profile's chat.plugins.marketplaces
  • enables the plugins whose catalog entries default to on (forge today); optional packages such as forge-planning stay opt-in
  • when GitHub Copilot is detected, installs any enabled plugin not yet cached locally by cloning saif-corp/forge and copying its files into ~/.copilot/installed-plugins/forge/<plugin>/ directly — see the reference doc for why this exists alongside copilot plugin install
  • always prints the equivalent copilot plugin install ... commands for that enabled subset too, whether or not the direct install ran

Every run writes:

{
  "enabledPlugins": {
    "forge@forge": true,
    "forge-planning@forge": false
  }
}

If you want repo-scoped plugin registration checked into the workspace instead, pass --local (or --scope project):

saif agent init --local

That writes <repo>/.github/copilot/settings.json, which is shared with other collaborators if committed. GitHub Copilot CLI's own plugin settings and permissions files still stay user-level.

Expected end state:

  • GitHub Copilot CLI and the GitHub Copilot app can see Forge in ~/.copilot/settings.json
  • VS Code knows about the Forge marketplace through chat.plugins.marketplaces
  • if GitHub Copilot was detected, the plugin files are already installed under ~/.copilot/installed-plugins/forge/; otherwise, run one of the printed copilot plugin install commands (or install from VS Code's Extensions view)
  • either way, the plugin can launch saif agent mcp automatically for MCP-backed tools

VS Code needs no separate install step here: it automatically discovers plugins installed under ~/.copilot/installed-plugins/, the same directory saif agent init writes into directly. The chat.plugins.marketplaces entry is only needed for browsing the Forge marketplace to install additional plugins later.

By default, agents should prefer the Forge MCP tools (list_commands, get_command, search_docs, search_services) for read-only SAIF lookups instead of shelling out to saif.

If an agent also needs to run saif shell commands directly in plan mode, grant that separately:

saif agent init --grant-permissions
Host What gets granted
VS Code Per-command chat.tools.terminal.autoApprove rules in .vscode/settings.json. Read-only saif commands are approved and mutating ones are explicitly denied.
GitHub Copilot CLI An all-or-nothing saif grant in ~/.copilot/permissions-config.json. Copilot CLI cannot scope grants per subcommand, so this approves every saif command, mutating ones included. Treat it as trusting the whole CLI.

See the SAIF CLI reference for the full command surface.

Install the Forge plugin packages

GitHub Copilot CLI discovers Forge's marketplace metadata from .github/plugin/marketplace.json. That catalog publishes two packages:

  • forge: the day-to-day Forge skills authored under .github/skills/, packaged into forge, plus the MCP server registrations from .github/plugins/forge/mcp.json — the shared Forge MCP server and the Mosaic design-system MCP server
  • forge-planning: the optional planning and artifact-authoring skills authored under .github/skills/, packaged into forge-planning

saif agent init registers those plugins and enables the default package set, and when GitHub Copilot is detected, installs any enabled package that isn't cached locally yet by cloning the repo directly (avoiding a copilot plugin install failure mode seen on some Windows machines — see the reference doc). If GitHub Copilot wasn't detected, first use may still require a manual install.

For the full skill inventory included in each package, see Agent Skills.

If you want the portable plugin install path in Copilot CLI, add the Forge marketplace once and then install the package you want:

copilot plugin marketplace add saif-corp/forge
copilot plugin install forge@forge

# Optional planning package
copilot plugin install forge-planning@forge

marketplace.json is a GitHub-Copilot-specific distribution shim. The portable Agent Plugins payloads remain .github/plugins/forge/ and .github/plugins/forge-planning/.

Azure operations are intentionally out of scope

Forge does not ship Azure operations skills such as azure-role-selector, azure-cost-optimize, azure-resource-health-diagnose, or entra-agent-user in either plugin package. That package boundary is intentional per ADR 0012.

If you need Azure role selection, cost optimization, resource health diagnostics, Entra agent-user management, or similar Azure operations workflows, install the Azure-owned distribution from microsoft/azure-skills. Its README describes that package as shipping Azure skills alongside the Azure MCP Server and Foundry MCP.

📖 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 for detailed guides

Common SAIF CLI Commands

Here are some frequently used commands to get you started:

# 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

📖 Additional Resources

Happy automating with SAIF CLI! 🎉