Skip to content

getting started installation

Lev edited this page Feb 19, 2026 · 1 revision

📦 Installation Guide

Complete installation instructions for ConcordIO tools and packages.

⚠️ Development-Time Toolchain
ConcordIO is a build-time dependency only. It runs during compilation and CI/CD to generate code, but does NOT deploy to production. The tools and tasks execute during the build process and are not bundled into your application binaries.

Prerequisites

Required

Optional (for specific features)

  • nuget CLI - Required for breaking and get-spec commands
    • Windows: choco install nuget.commandline
    • macOS: brew install nuget
    • Linux: Download from nuget.org

Installing the CLI Tool

Global Installation (Recommended)

Install the tool globally so it's available from any directory:

dotnet tool install --global ConcordIO.Tool

Verify the installation:

concordio --version

Update Global Tool

Update to the latest version:

dotnet tool update --global ConcordIO.Tool

Uninstall Global Tool

dotnet tool uninstall --global ConcordIO.Tool

Local Installation (Project-Specific)

For project-specific tooling, install as a local tool:

# Create a tool manifest if it doesn't exist
dotnet new tool-manifest

# Install the tool locally
dotnet tool install ConcordIO.Tool

Run with dotnet prefix:

dotnet concordio --version

Update local tool:

dotnet tool update ConcordIO.Tool

Version Pinning

Pin to a specific version in your project:

dotnet tool install ConcordIO.Tool --version 1.2.3

Or in .config/dotnet-tools.json:

{
  "version": 1,
  "isRoot": true,
  "tools": {
    "concordio.tool": {
      "version": "1.2.3",
      "commands": [
        "concordio"
      ]
    }
  }
}

Installing MSBuild Packages

AsyncAPI Client Package

For generating C# types from AsyncAPI specifications:

<ItemGroup>
  <PackageReference Include="ConcordIO.AsyncApi.Client" Version="0.1.0">
    <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
    <PrivateAssets>all</PrivateAssets>
  </PackageReference>
</ItemGroup>

AsyncAPI Server Package

For generating AsyncAPI specifications from .NET types:

<ItemGroup>
  <PackageReference Include="ConcordIO.AsyncApi.Server" Version="0.1.0">
    <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
    <PrivateAssets>all</PrivateAssets>
  </PackageReference>
</ItemGroup>

Package Sources

GitHub Packages (Default)

ConcordIO packages are published to GitHub Packages by default. Add the source:

dotnet nuget add source https://nuget.pkg.github.com/LevDevIO/index.json \
  --name github-levdevio

Or in NuGet.config:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <packageSources>
    <add key="github-levdevio" value="https://nuget.pkg.github.com/LevDevIO/index.json" />
  </packageSources>
</configuration>

Authentication: While this repository is public, GitHub Packages typically requires authentication even for consuming public packages. You may need to configure a Personal Access Token (PAT) with read:packages scope:

  1. Create a PAT: https://github.com/settings/tokens/new (select read:packages scope)
  2. Add to NuGet.config:
<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <packageSources>
    <add key="github-levdevio" value="https://nuget.pkg.github.com/LevDevIO/index.json" />
  </packageSources>
  <packageSourceCredentials>
    <github-levdevio>
      <add key="Username" value="YOUR_GITHUB_USERNAME" />
      <add key="ClearTextPassword" value="YOUR_PAT_TOKEN" />
    </github-levdevio>
  </packageSourceCredentials>
</configuration>

Alternatively, use the dotnet nuget add source command with --username and --password flags.

NuGet.org (Public Releases)

Stable releases are published to NuGet.org and don't require additional configuration:

dotnet tool install --global ConcordIO.Tool

Platform-Specific Notes

Windows

No special configuration needed. Ensure:

  • .NET SDK is installed
  • PowerShell or Command Prompt is used
  • PATH includes .NET tools: %USERPROFILE%\.dotnet\tools

macOS

Ensure tools are on PATH:

echo 'export PATH="$PATH:$HOME/.dotnet/tools"' >> ~/.zshrc
source ~/.zshrc

For Apple Silicon (M1/M2):

  • .NET SDK includes ARM64 support
  • ConcordIO bundles universal macOS binaries

Linux

Add tools to PATH in .bashrc or .zshrc:

echo 'export PATH="$PATH:$HOME/.dotnet/tools"' >> ~/.bashrc
source ~/.bashrc

Docker

Dockerfile example:

FROM mcr.microsoft.com/dotnet/sdk:10.0

# Install ConcordIO
RUN dotnet tool install --global ConcordIO.Tool

# Add to PATH
ENV PATH="$PATH:/root/.dotnet/tools"

# Verify installation
RUN concordio --version

Offline Installation

For environments without internet access:

  1. Download the package on an online machine:
dotnet tool install --global ConcordIO.Tool --tool-path ./tools
  1. Copy ./tools to the offline machine

  2. Install from local files:

dotnet tool install --global ConcordIO.Tool --add-source ./tools

Troubleshooting Installation

Tool not found after installation

Symptom: concordio: command not found

Solution: Add .NET tools to PATH:

# Linux/macOS
export PATH="$PATH:$HOME/.dotnet/tools"

# Windows (PowerShell)
$env:PATH += ";$env:USERPROFILE\.dotnet\tools"

Permission denied (Linux/macOS)

Symptom: Permission denied when installing

Solution: Don't use sudo with dotnet tool install. It should install to your user directory.

Version conflicts

Symptom: A newer version of the tool is already installed

Solution: Update instead of install:

dotnet tool update --global ConcordIO.Tool

Or uninstall first:

dotnet tool uninstall --global ConcordIO.Tool
dotnet tool install --global ConcordIO.Tool

Package source authentication issues

Symptom: 401 Unauthorized when restoring packages

Solution: For private feeds, configure authentication:

dotnet nuget add source https://your-feed.com/nuget \
  --name private-feed \
  --username USERNAME \
  --password PASSWORD \
  --store-password-in-clear-text

Verifying Installation

Check everything is working:

# CLI tool
concordio --version

# .NET SDK
dotnet --version

# nuget CLI (optional)
nuget help

# List installed tools
dotnet tool list --global

Next Steps

Getting Help

Clone this wiki locally