Edit

Use the Foundry Local CLI (preview)

Important

  • Foundry Local CLI is available in preview. Public preview releases provide early access to features that are in active deployment.
  • Features, approaches, and processes can change or have limited capabilities, before General Availability (GA).

The Foundry Local command-line interface (CLI) lets you browse the model catalog, run models interactively, and manage your local cache directly from the terminal. The CLI is useful for exploring available models, testing prompts, and preparing your environment before writing application code.

Note

The CLI is a companion tool for exploration and management. For building applications, use the Foundry Local SDK, which embeds the runtime directly in your app.

Prerequisites

  • A terminal (PowerShell, Terminal, or similar).
  • Internet access for first-time model and execution provider downloads.

Install the Foundry Local CLI

Install Foundry Local by using the package manager for your operating system.

winget install Microsoft.FoundryLocal

Verify the installation:

foundry --version

Tip

If you see a service connection error after installation (for example, Request to local service failed), run foundry service restart.

Browse the model catalog

List all models available for local inference:

foundry model list

On first run, Foundry Local downloads execution providers for your hardware before displaying the catalog.

Filter the list by hardware device, task type, or execution provider:

foundry model list --filter device=GPU
foundry model list --filter task=chat-completion

Get detailed information about a specific model:

foundry model info phi-4-mini

Tip

Use a model alias (like phi-4-mini) to let Foundry Local automatically select the best variant for your hardware. Use a full model ID to target a specific variant.

Run a model interactively

Start an interactive chat session with a model:

foundry model run phi-4-mini

Foundry Local downloads the model on first run, loads it into memory, and opens a chat prompt. Type a message and press Enter to get a response:

> What is the golden ratio?

Type /exit to end the session.

Download a model without running it

Pre-download a model to the local cache for later use:

foundry model download phi-4-mini

This step is useful for preparing models in advance, especially when you expect to be offline later.

Manage the model cache

View models stored locally:

foundry cache list

Check the current cache location:

foundry cache location

Remove a model you no longer need:

foundry cache remove phi-4-mini

Change the cache directory (for example, to move models to a larger disk):

foundry cache cd /path/to/new/cache

Check service status

Verify the Foundry Local service is running and get the local endpoint URL:

foundry service status

If the service isn't responding, restart it:

foundry service restart

Related content

  • Last updated on