# Install / update the CLI

The `legends` CLI is a .NET global tool published to an internal Azure DevOps
NuGet feed. It does two jobs: it installs the doc gen tooling into a repository
you want to document, and it queries documentation that has already been
published to this portal.

## Prerequisites

- **.NET 10 SDK** — the tool targets `net10.0`. Check with `dotnet --list-sdks`.
- **Azure DevOps access** to the `SAIFCorporation` organization, for the NuGet feed.
- **API key** — `legends search`, `legends chat`, `legends list`,
  `legends oracle` and `legends sqlserver` call the Legends CLI Experience API
  with an API key you store once per environment with `legends login` (Windows
  only). [Quick start step 1](quick-start.md#1-log-in-to-the-cli) covers getting
  the key from Keeper. The optional [Holocron MCP](holocron-mcp.md) tools use
  your Entra sign-in through `legends auth` instead.

## Install

```powershell
dotnet tool install --global Legends.CLI --add-source https://pkgs.dev.azure.com/SAIFCorporation/_packaging/SAIFCorporation/nuget/v3/index.json
```

If you already have the `SAIFCorporation` feed configured in your NuGet.config,
the short form works too:

```powershell
dotnet tool install --global Legends.CLI
```

Verify the install:

```powershell
legends --version
legends --help
```

!!! tip "Feed authentication"
    If the install fails with a 401, authenticate to the feed first. The
    Azure Artifacts Credential Provider is the usual fix; once installed,
    re-run the `dotnet tool install` command and complete the device-code
    prompt.

## Update

The CLI knows how to update itself:

```powershell
legends update             # report installed vs. latest
legends update --install   # download and install the latest version
```

Add `--prerelease` to pick up preview builds published from non-`main` branches:

```powershell
legends update --install --prerelease
```

!!! note "Why `--install` looks like it does nothing at first"
    On Windows the running executable holds a lock on its own files, so
    `--install` hands the upgrade to a short-lived PowerShell helper that runs
    after the CLI exits. Give it a few seconds, then confirm with
    `legends --version`.

The CLI also runs a background version check at most once per day and prints a
notice to **stderr** when a newer version exists:

```text
A new version of legends is available: 1.1.6 -> 1.1.8
Run: legends update --install
```

This is informational only. Copilot agents are explicitly instructed to ignore
it — if you see it inside an agent transcript, it is not an error.

## Uninstall / reinstall

```powershell
dotnet tool uninstall --global Legends.CLI
```

Reinstalling is the fastest way out of a broken or partially-updated install.

## Command surface

| Command | Purpose |
| --- | --- |
| `legends init` | Install or refresh the doc gen tooling in the current repository. |
| `legends search "<query>"` | Search published documentation. |
| `legends chat` | Interactive multi-turn chat against published documentation. |
| `legends list <libraries\|repos\|doc-types>` | List valid filter values from the search index. |
| `legends env` | Show or change the active environment (`legends env --set TEST`). |
| `legends login` | Manage stored API key credentials (`list`, `test`, `clear`). Windows only. |
| `legends auth` | Entra sign-in for the Holocron MCP tools (`generate`, `validate`, `clear`). All platforms. |
| `legends agent init` | Register the Holocron MCP server with your Copilot hosts. See [Holocron MCP](holocron-mcp.md). |
| `legends agent mcp` | The local stdio MCP server that Copilot starts for Holocron. You do not run it yourself. |
| `legends update` | Check for and install a newer CLI. |
| `legends nuget check` / `legends nuget exists <pkg>` | SAIF NuGet feed connectivity and package lookup. |
| `legends oracle query --owner <o> --name <n>` | Retrieve Oracle stored procedure / package source. |
| `legends sqlserver query` | Retrieve SQL Server stored procedure source. |
| `legends readme` | Open the tooling repository in a browser (also `legends --readme`). |

Examples:

```powershell
legends search "What is clsDataPortalInfo?" --library SAIF.Framework.Core
legends chat --library SAIF.Framework.Core
legends list libraries --repo-name IT.BOF.Framework
legends init --dry-run
```

!!! warning "`--library` takes the canonical name, not the slug"
    Filters are exact metadata matches. Pass `SAIF.Framework.Core`, never the
    folder slug `saif-framework-core`, the repository name `IT.BOF.Framework`,
    or a NuGet package id. A wrong value returns zero results **with no error**.
    Use `legends list libraries` to discover valid values.

## Next

Once the CLI is installed, continue with the [Quick start](quick-start.md). Its
first step, [Log in to the CLI](quick-start.md#1-log-in-to-the-cli), covers
getting an API key from Keeper and storing it with `legends login`.

Optionally, set up [Holocron MCP](holocron-mcp.md) to give GitHub Copilot agents
the same documentation search and answers as MCP tools. Doc gen uses them when
they are available.