spire.cli 0.2.1

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 (for 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.

How It Works

Spire extends Aspire's native .aspire/settings.json file with a sharedResources section that describes how each service can run (as a project or container). This file lives in the AppHost's .aspire directory and uses relative paths.

A global configuration file (~/.aspire/spire/aspire-shared-resources.json) aggregates all resources across repositories with absolute paths. Repository-scoped overrides (created via CLI commands) can further customize resources per repo. MSBuild targets invoke the Spire CLI to import resources at build time, and a Roslyn source generator creates type-safe builders at compile time.

Core Flows

Generate (producer)

Scan an existing repository for projects and containers, then produce shared resource definitions in .aspire/settings.json.

spire resource generate <path>

This discovers .csproj files and container definitions, then writes (or updates) the sharedResources section in .aspire/settings.json. The global config at ~/.aspire/spire/aspire-shared-resources.json is also updated with absolute paths.

Import (consumer)

Import shared resources from .aspire/settings.json files found in the current git repository into the global config.

spire resource import

This walks the git repository looking for .aspire/settings.json files, converts relative paths to absolute, and merges entries into ~/.aspire/spire/aspire-shared-resources.json. The MSBuild targets call this automatically before the source generator runs, so consuming AppHosts stay in sync without manual steps.

At Build Time

1. MSBuild targets invoke spire resource import to sync .aspire/settings.json files into the global config.
2. spire resource list --level repo --json outputs the merged configuration as JSON.
3. The source generator reads this JSON, matching the schema structure (resources map with mode, containerMode, projectMode), and emits type-safe builder.Add{ResourceName}() extension methods.
4. A generated AddSharedResourcesConfiguration() method embeds the resolved JSON as an in-memory configuration source, so generated code reads values like resources:{id}:mode from IConfiguration at runtime.

Resource Management

All resource commands operate on both .aspire/settings.json and the global config. The settings file is the portable, version-controlled source of truth; the global config is the local runtime state. Configuration is layered with increasing priority: global → repository overrides → environment variables (ASPIRE_*).

CLI Commands

Configuration

MSBuild Properties

Installation

Add the Shirubasoft.Spire.Hosting package to your AppHost project. This provides the MSBuild targets, source generator, and runtime types needed to use shared resources:

dotnet add package Shirubasoft.Spire.Hosting

Then install the Spire CLI as a global .NET tool:

dotnet tool install -g spire.cli

Automatic CLI Install

If you'd prefer the CLI to be installed (or updated) automatically at build time, set the SpireAutoInstallCli property in your AppHost project:

<PropertyGroup>
  <SpireAutoInstallCli>true</SpireAutoInstallCli>
</PropertyGroup>

When enabled, the build will run dotnet tool install -g spire.cli before checking CLI availability. If the install fails (e.g., no network), the build continues and falls back to the normal availability check.

Requirements

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

License

MIT