Command Line Interface (CLI)

Most of Charon functionality could be accessed via CLI commands. The application uses GNU-style long options (--parameterName <value>). You should be familiar with the terminal on your OS to fully tap the potential of the CLI.

Requirements

Charon is distributed as a .NET tool, so the .NET SDK is the only prerequisite.

.NET SDK 10 or later — recommended. Enables dnx, which runs Charon without installing anything.
.NET SDK 8 or 9 — supported through bootstrap scripts or a classic tool install. dnx is not available on these versions.

Check which version you have:

dotnet --version
#> 10.0.100

If the command is not found, the SDK is not installed or not on PATH.

Installation

Option 1: dnx (recommended, .NET SDK 10+)

.NET SDK 10 introduced dnx, a runner for .NET tools similar to npx. It downloads and executes the tool on demand without registering it in the global or local tool manifest. Nothing to install, nothing to add to PATH:

# run any charon command
dnx dotnet-charon -- DATA EXPORT --help

# use this form when dnx is not registered in PATH
dotnet dnx dotnet-charon -- DATA EXPORT --help

Everything after -- is passed to Charon. The tool is cached by NuGet after the first run, so subsequent invocations start immediately.

Pin a version for reproducible builds:

dnx dotnet-charon@2026.3.4 -- VERSION

This is the notation used throughout the rest of the documentation. If you installed Charon in another way, see Choosing how to invoke Charon for the equivalent command.

Option 2: dotnet tool (.NET SDK 8+)

Installs Charon into the global tool store or into a local tool manifest next to your project.

# install charon globally
dotnet tool install --global dotnet-charon

# install charon in current working directory
dotnet tool install dotnet-charon --local --create-manifest-if-needed

# pin a specific version (recommended for CI)
dotnet tool install --global dotnet-charon --version 2026.3.4

If the repository already contains a .config/dotnet-tools.json manifest, you do not install anything — just restore it:

dotnet tool restore

To update an installed tool:

# update global tool
dotnet tool update --global dotnet-charon

# update local tool
dotnet tool update dotnet-charon --local

To remove it:

dotnet tool uninstall --global dotnet-charon
dotnet tool uninstall dotnet-charon --local

Adding the global tool to PATH

A global tool is launched by the bare charon command, but only if the .NET tools directory is on PATH. On Windows this normally happens automatically; on macOS and Linux you have to do it yourself.

Windows

The installer adds %USERPROFILE%\.dotnet\tools to PATH. Open a new terminal window after installing so it picks up the change. To add it manually:

setx PATH "%PATH%;%USERPROFILE%\.dotnet\tools"

macOS

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

Linux

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

A local tool is never placed on PATH. It is always invoked through dotnet from the directory containing the manifest — see Choosing how to invoke Charon.

Option 3: Bootstrap scripts (.NET SDK 8+)

Use this when dnx is unavailable (.NET SDK 8 or 9) and you would rather not manage the tool manifest yourself. The scripts create a local tool manifest, install or update Charon in it, and then run it.

RunCharon.bat (Windows)

RunCharon.sh (Linux, macOS)

Both scripts require the dotnet tool to be included in the system PATH.

Windows

mkdir Charon
cd Charon
curl -O https://raw.githubusercontent.com/gamedevware/charon/main/scripts/bootstrap/RunCharon.bat

REM everything after the script name is your command
.\RunCharon.bat DATA EXPORT --help

Linux, macOS

mkdir Charon
cd Charon
curl -O https://raw.githubusercontent.com/gamedevware/charon/main/scripts/bootstrap/RunCharon.sh

chmod +x ./RunCharon.sh

# everything after the script name is your command
./RunCharon.sh DATA EXPORT --help

Verifying the installation

Run the VERSION command. It prints the tool version and exits with code 0:

dnx

dnx dotnet-charon -- VERSION

Global tool

charon VERSION
dotnet tool list --global

Local tool

dotnet charon VERSION
dotnet tool list --local

Bootstrap script

# Windows
.\RunCharon.bat VERSION

# Linux, macOS
./RunCharon.sh VERSION

If charon is reported as an unknown command after a global install, the .NET tools directory is missing from PATH — see Adding the global tool to PATH.

Choosing how to invoke Charon

Every example in this documentation is written as dnx dotnet-charon -- <VERB>. If you installed Charon in another way, substitute the leading part of the command:

Installation	Command prefix
dnx (.NET SDK 10+)	`dnx dotnet-charon --`
Global tool	`charon`
Local tool	`dotnet charon`
Bootstrap script	`.\RunCharon.bat` or `./RunCharon.sh`

For example, these four commands are equivalent:

dnx dotnet-charon -- DATA VALIDATE --dataBase ./gamedata.json
charon DATA VALIDATE --dataBase ./gamedata.json
dotnet charon DATA VALIDATE --dataBase ./gamedata.json
./RunCharon.sh DATA VALIDATE --dataBase ./gamedata.json

Command Syntax

Commands have the following syntax:

dnx dotnet-charon -- VERB [SUB-VERB] --parameterName <parameter-value>

# parameters can have more than one value.
# Use space to separate values
dnx dotnet-charon -- DATA EXPORT --schemas Item Armor "Project Settings" Quest

# if your value contains a space, put it inside the quotation marks.
dnx dotnet-charon -- DATA EXPORT --dataBase "c:\my application\gamedata.json"

# some parameters don't require a value (e.g. flag).
dnx dotnet-charon -- VERSION --verbose

Available verbs are INIT, DATA, GENERATE, SERVER, MCP and VERSION. Verbs are case-insensitive; they are written in upper case in this documentation to stand out from parameters.

Running on Windows, macOS and Linux

Charon behaves identically on all platforms, but the shell around it does not. Examples in this documentation use Bash syntax. Keep the following in mind.

Splitting a long command across lines. The trailing \ used in the examples is a Bash/Zsh continuation character. It is not understood by Windows shells:

Bash / Zsh (macOS, Linux)

dnx dotnet-charon -- DATA EXPORT \
  --dataBase ./gamedata.json \
  --output ./characters.json

PowerShell

dnx dotnet-charon -- DATA EXPORT `
  --dataBase ./gamedata.json `
  --output ./characters.json

Command Prompt

dnx dotnet-charon -- DATA EXPORT ^
  --dataBase .\gamedata.json ^
  --output .\characters.json

When in doubt, put the whole command on a single line — that works in every shell.

Wildcards. Parameters like --schemas accept * wildcards. Bash and Zsh expand * against file names before Charon ever sees it, so always quote such values:

# correct
dnx dotnet-charon -- DATA EXPORT --schemas "Item*"

# wrong on macOS/Linux — the shell replaces Item* with matching file names
dnx dotnet-charon -- DATA EXPORT --schemas Item*

Environment variables. Setting CHARON_API_KEY differs per shell:

Bash / Zsh

export CHARON_API_KEY=87758CC0D7C745D0948F2A8AFE61BC81

PowerShell

$env:CHARON_API_KEY = "87758CC0D7C745D0948F2A8AFE61BC81"

Command Prompt

set CHARON_API_KEY=87758CC0D7C745D0948F2A8AFE61BC81

Absolute and relative paths

When running commands, it’s crucial to be aware of whether you are using absolute or relative paths to files.

Understanding Paths

Absolute Path: An absolute path defines a file or directory’s location in relation to the root directory. In Linux and macOS, it starts from the root /, while in Windows, it begins with a drive letter (like C:\).
- Example for Linux/macOS: /usr/local/share/mygame
- Example for Windows: C:\Program Files\MyGame
Relative Path: A relative path references a file or directory in relation to the current working directory, without starting with a root slash or drive letter.
- Example: If currently in /home/user/Documents, a file in /home/user/Documents/Projects would have the relative path Projects/FileName.

Usage in Terminals

Windows (Command Prompt and PowerShell): Paths use backslashes (\). Absolute paths start with a drive letter (like C:\Users\Name), while relative paths use the file name or paths like subfolder\file.txt. Forward slashes are also accepted, so ./gamedata.json works too.
macOS/Linux Terminal: Paths are denoted with forward slashes (/). Absolute paths begin from the root (/), and relative paths use ./ for the current directory or ../ to go up one level.

Getting Help Text

To display the list of available commands add --help or /?.

dnx dotnet-charon -- --help

#> Verbs:
#>   INIT        Initialize a new, empty game data file at the specified path.
#>   MCP         Start an MCP (Model Context Protocol) server for AI assistant integration via stdio.
#>               Usage: claude mcp add --transport stdio charon -- charon MCP
#>   SERVER      Commands for starting and managing the embedded HTTP server.
#>   DATA        Commands for reading, writing, importing, and exporting game data.
#>   GENERATE    Commands for generating typed source code from game data schemas.
#>   VERSION     Print current product version.

The same flag works for any verb and sub-verb:

dnx dotnet-charon -- DATA --help

dnx dotnet-charon -- DATA EXPORT --help

#> Usage:
#>   DATA EXPORT --dataBase <URI> [--schemas [<TEXT>]] [--properties [<TEXT>]] [--languages [<TEXT>]] [--output <TEXT>
#>               ] [--outputFormat <TEXT>] [--outputFormattingOptions [<TEXT>]] [--mode <EXPORTMODE>] [--credentials [<
#>               TEXT>]]