CLI Access to charon.live

The web version of Charon provides a REST API and CLI for accessing and modifying game data remotely. To authenticate CLI commands against a web project, users need to generate an API Key in the API Keys section of their User Profile.

With an API Key, Charon integrates into any existing workflow - exporting data into a local repository, importing designer edits back to the server, generating source code, or running validation in CI.

Installing the CLI

Charon requires the .NET SDK 10 or later. There is nothing to install - dnx downloads and runs the tool on demand:

dnx dotnet-charon -- DATA EXPORT --help

On .NET SDK 8 or 9 dnx is unavailable; install dotnet-charon as a global tool instead and call it as charon:

dotnet tool install -g dotnet-charon
charon DATA EXPORT --help

See Command Line Interface (CLI) for full installation options.

Finding Your Project URL

Every web project has a stable URL that can be passed to the --dataBase parameter. You can find it in your browser’s address bar while viewing any page inside the project on charon.live - it has the form:

https://charon.live/view/data/<Project>/
https://charon.live/view/data/<Project>/<Branch>/

For example:

https://charon.live/view/data/My_Game/
https://charon.live/view/data/My_Game/develop/

Use the branch-specific URL when you want to target a particular branch (e.g. main, develop).

Generating an API Key

  1. Navigate to the API Keys section in your User Profile → API Keys and click Create API Key….

  2. Copy the generated API Key - it is shown only once.

  3. Store the key securely (e.g. in a password manager or CI secret store).

Use the API Key in:

  • The --credentials parameter of any CLI command.

  • The CHARON_API_KEY environment variable (the CLI reads it automatically).

  • The Authenticate HTTP header when calling the REST API directly.

Authentication

Pass the API Key either as an explicit parameter or as an environment variable:

# Explicit parameter
dnx dotnet-charon -- DATA EXPORT \
  --dataBase "https://charon.live/view/data/My_Game/develop/" \
  --output "./gamedata.json" \
  --outputFormat json \
  --credentials "<API-Key>"

# Environment variable - picked up automatically by all commands
export CHARON_API_KEY="<API-Key>"
dnx dotnet-charon -- DATA EXPORT \
  --dataBase "https://charon.live/view/data/My_Game/develop/" \
  --output "./gamedata.json" \
  --outputFormat json

The environment variable takes precedence when both are supplied. In CI pipelines, store the key as a secret and inject it via CHARON_API_KEY rather than hard-coding it in pipeline files.

Common Operations

Export Data

Export all documents (or a subset by schema) from a web project into a local file:

# Export all schemas
dnx dotnet-charon -- DATA EXPORT \
  --dataBase "https://charon.live/view/data/My_Game/develop/" \
  --output "./gamedata.json" \
  --outputFormat json \
  --credentials "<API-Key>"

# Export a specific schema
dnx dotnet-charon -- DATA EXPORT \
  --dataBase "https://charon.live/view/data/My_Game/develop/" \
  --schemas Character \
  --output "./characters.json" \
  --outputFormat json \
  --credentials "<API-Key>"

# Export publication-ready data (strips non-essential fields)
dnx dotnet-charon -- DATA EXPORT \
  --dataBase "https://charon.live/view/data/My_Game/develop/" \
  --mode publication \
  --output "./StreamingAssets/gamedata.json" \
  --outputFormat json \
  --credentials "<API-Key>"

Import Data

Push local edits back to the web project:

# Update existing documents (safe - no creates or deletes)
dnx dotnet-charon -- DATA IMPORT \
  --dataBase "https://charon.live/view/data/My_Game/develop/" \
  --schemas Character \
  --input "./characters.json" \
  --inputFormat json \
  --mode safeUpdate \
  --credentials "<API-Key>"

# Create and update documents
dnx dotnet-charon -- DATA IMPORT \
  --dataBase "https://charon.live/view/data/My_Game/develop/" \
  --input "./gamedata.json" \
  --inputFormat json \
  --mode createAndUpdate \
  --credentials "<API-Key>"

Generate Source Code

Generate C# classes directly from the web project without downloading the data first:

dnx dotnet-charon -- GENERATE CSHARPCODE \
  --dataBase "https://charon.live/view/data/My_Game/develop/" \
  --namespace "MyGame.Parameters" \
  --outputDirectory "./Assets/Scripts/Generated" \
  --clearOutputDirectory \
  --credentials "<API-Key>"

Validate Data

Check data integrity - useful before a release or as a CI gate:

# Print a validation report to stdout
dnx dotnet-charon -- DATA VALIDATE \
  --dataBase "https://charon.live/view/data/My_Game/develop/" \
  --validationOptions checkRequirements checkReferences checkFormat \
  --credentials "<API-Key>"

# Exit with code 1 if any errors are found (CI-friendly)
dnx dotnet-charon -- DATA VALIDATE \
  --dataBase "https://charon.live/view/data/My_Game/develop/" \
  --validationOptions checkRequirements checkReferences checkFormat \
  --output err \
  --credentials "<API-Key>"

Backup

Create a local backup archive of a web project:

dnx dotnet-charon -- DATA BACKUP \
  --dataBase "https://charon.live/view/data/My_Game/develop/" \
  --output "./backup_my_game.zip" \
  --credentials "<API-Key>"

See also