Skip to main content

​
Command Reference

The FG Character Extractor is a simple command-line tool with minimal options, designed to be easy to use while providing powerful character extraction capabilities.

​
Basic Syntax

fg-char-extract [filename]
​
filename
string
default:"db.xml"
Path to the Fantasy Grounds campaign database file. If not specified, the tool looks for db.xml in the current directory.

​
Command Behavior

When you run fg-char-extract, the tool:
1

Opens the database file

Opens the specified db.xml file (or db.xml in the current directory if no file is specified)
2

Parses character data

Scans for the <charsheet> or <charsheets> section and extracts all character entries
3

Filters sensitive data

Removes tags matching the pattern public or holder* from each character
4

Calculates skill totals

Automatically computes skill totals based on ability bonuses and proficiency values:
total = ability_bonus + (proficiency * proficiency_bonus)
5

Writes output files

Creates individual XML files named character_<ID>_<Level>.xml in the current directory

​
Exit Codes

The tool uses standard Unix exit codes:
Exit CodeMeaningDescription
0SuccessAll characters extracted successfully
1ErrorAn error occurred (see stderr for details)

​
Usage Examples

​
Default Usage

Extract characters from db.xml in the current directory: 
fg-char-extract

​
Specify File Path

Extract characters from a specific file: 
fg-char-extract /path/to/campaign/db.xml
Windows
fg-char-extract C:\Users\YourName\AppData\Roaming\SmiteWorks\Fantasy Grounds\campaigns\MyCampaign\db.xml

​
Relative Paths

Use relative paths from your current location: 
fg-char-extract ../OtherCampaign/db.xml

​
Output

The tool provides progress information via structured logging:
Example output
2026/03/08 14:30:15 INFO Character extracted successfully filename=character_id-00001_5.xml
2026/03/08 14:30:15 INFO Character extracted successfully filename=character_id-00002_3.xml
2026/03/08 14:30:15 INFO Character extracted successfully filename=character_id-00003_7.xml
The tool uses Go’s slog package for structured logging, which outputs in a human-readable format by default.

​
Error Handling

If an error occurs, the tool will:
  1. Log the error to stderr using structured logging
  2. Exit with code 1

​
Common Errors

ERROR Execution failed error="opening db.xml: no such file or directory"
Solution: Verify the file path and ensure the file exists. Use an absolute path if needed.
ERROR Execution failed error="opening /path/to/db.xml: permission denied"
Solution: Check file permissions. You may need read access to the source file and write access to the output directory.
ERROR Execution failed error="decoding token: XML syntax error on line 42: unexpected EOF"
Solution: The db.xml file may be corrupted or incomplete. Verify the file integrity or restore from backup.
ERROR Execution failed error="writing character id-00001: no space left on device"
Solution: Free up disk space or write to a different directory with available space.

​
Source Code Reference

The command-line argument parsing is handled in main.go:
main.go:13-17
func main() {
	filename := "db.xml"
	if len(os.Args) > 1 {
		filename = os.Args[1]
	}
Error handling and exit behavior:
main.go:19-22
	if err := run(filename); err != nil {
		slog.Error("Execution failed", "error", err)
		os.Exit(1)
	}

​
Next Steps

Output Format

Learn about the structure of extracted XML files

Usage Examples

See real-world usage scenarios and patterns

Build docs developers (and LLMs) love

Get started for freeTalk to us