spire.cli 0.3.0

Spire

Share .NET Aspire services across multiple repositories. A service runs as a Project in its home repo and as a Container everywhere else — with a single declaration.

The Problem

In a multi-repo setup, you want payments-service to:

• Run as a Project in the payments repo (inner-loop development with hot reload, debugging, etc.)
• Run as a Container in the frontend repo (consuming it as a dependency)

Aspire has no built-in way to do this. You'd need to maintain separate AppHost configurations, manually build container images, and keep them in sync.

Quick Start

1. Install

# Add the hosting package to your AppHost
dotnet add package Shirubasoft.Spire.Hosting

# Install the CLI
dotnet tool install -g spire.cli

To auto-install the CLI at build time, set <SpireAutoInstallCli>true</SpireAutoInstallCli> in your AppHost project. See Configuration for details.

2. Generate a shared resource (producer repo)

spire resource generate ./src/MyService

This scans the path for a .csproj or Dockerfile, creates a resource definition in .aspire/settings.json, and registers it in the global config.

3. Import resources (consumer repo)

spire resource import

This happens automatically at build time via MSBuild targets, but you can run it manually too.

4. Use in your AppHost

var builder = DistributedApplication.CreateBuilder(args);
builder.Configuration.AddSharedResourcesConfiguration();

var api = builder.AddPaymentsService()        // generated method
    .ConfigureContainer(b => b.WithHttpEndpoint(targetPort: 8080))
    .WithHttpHealthCheck("/health");

builder.Build().Run();

The source generator creates type-safe Add{Name}() extension methods for each registered resource. See Aspire Extension Methods for how standard Aspire methods like .WithHttpEndpoint() and .WaitFor() work on shared resources.

5. Toggle modes

# Interactive
spire modes

# Non-interactive
spire modes --id payments-service --mode Container

CLI Commands

See CLI Reference for all flags and options.

Configuration Files

See Configuration for details on layering, MSBuild properties, and JSON schemas.

How It Works

At build time, MSBuild targets invoke the Spire CLI to import resources and forward them to a Roslyn source generator that emits type-safe builders. At runtime, resources resolve to either a ProjectResource or ContainerResource based on their configured mode.

See Architecture for the full build-time and runtime flow.

Documentation

• CLI Reference — full command, flag, and option reference
• Configuration — config files, layering, MSBuild properties, JSON schemas
• Architecture — build-time flow, source generator, runtime behavior
• Aspire Extension Methods — using standard Aspire methods on shared resources

Requirements

• .NET 10.0 or later
• .NET Aspire 13.1 or later
• Docker or Podman (for container mode)

License

MIT