Skip to content

Getting Started for Dungeon Masters

This guide walks you through setting up JickleJime, ingesting your first documents, and searching your campaign knowledge base.

Prerequisites

  • .NET 10 SDK or later
  • Azure CLI — logged in with az login
  • Terraform — infrastructure is provisioned via the infra/ directory
  • An Azure subscription with:
    • Azure OpenAI (gpt-4o and text-embedding-3-small deployments)
    • Azure AI Document Intelligence
    • Azure Database for PostgreSQL Flexible Server (provisioned via terraform apply in infra/)

1. Configure credentials

JickleJime uses .NET user secrets for local development. The easiest way to configure them is from the Terraform output — run this from the infra/ directory:

terraform output -raw user_secrets_commands | bash

This sets all required endpoints, the PostgreSQL connection string, and enables Entra ID database authentication automatically.

Manual configuration

If you prefer to set secrets individually, run these from the repository root:

dotnet user-secrets set "Jime:AzureOpenAiEndpoint" "https://your-resource.openai.azure.com/" --project src/JickleJime.Cli
dotnet user-secrets set "Jime:DocumentIntelligenceEndpoint" "https://your-resource.cognitiveservices.azure.com/" --project src/JickleJime.Cli
dotnet user-secrets set "Jime:PostgresConnectionString" "Host=<server>.postgres.database.azure.com;Port=5432;Database=jicklejime;Username=<postgres-role-name>;Ssl Mode=VerifyFull" --project src/JickleJime.Cli
dotnet user-secrets set "Jime:UsePostgresEntraAuth" "true" --project src/JickleJime.Cli

Replace <server> with your PostgreSQL server name and <postgres-role-name> with the PostgreSQL role name configured in Terraform (admin_user_principal_name). The UsePostgresEntraAuth setting tells JickleJime to authenticate using your az login session instead of a password.

See the Configuration Reference for all available settings.

2. Ingest a document

jime ingest shadowdark-rules.pdf

This extracts text from the PDF using Azure Document Intelligence, chunks it into passages, generates embeddings, and stores everything in the vector database. Duplicate chunks are automatically skipped, so re-running is safe.

3. Organize your documents

After ingesting, categorize and describe your documents:

# Assign categories for filtering
jime docs set-category "shadowdark-rules.pdf" "rules"

# Add a description
jime docs describe "shadowdark-rules.pdf" "Core Shadowdark RPG ruleset"

# Control visibility — hide DM-only content from players
jime docs set-scope "monster-stats.pdf" "dm-only"

4. Search and chat

# Quick search
jime search "How do critical hits work?"

# Interactive chat with follow-up questions
jime chat

# Single question with category filter
jime chat "What spells are available at level 1?" --category rules

5. Manage your campaign

# Add players
jime player add "Alice"
jime player add "Bob"

# Create a campaign
jime campaign add "The Lost Mines" -d "A treasure-hunting adventure"

# Add characters
jime character add "Thorgrim" --player "Alice" --campaign "The Lost Mines"

What's next?