Persona Forge#

Utility toolkit v2.0.0 — run, check, convert, analyze, and manage utility tasks from the command line.

Commands#

All commands follow the pattern: persona-forge <command> [input]

When called without input, each command displays its recent entries. When called with input, it records a new timestamped entry.

CommandDescriptionrunRecord or view run entriescheckRecord or view check entriesconvertRecord or view convert entriesanalyzeRecord or view analyze entriesgenerateRecord or view generate entriespreviewRecord or view preview entriesbatchRecord or view batch processing entriescompareRecord or view compare entriesexportRecord or view export entriesconfigRecord or view config entriesstatusRecord or view status entriesreportRecord or view report entriesstatsSummary statistics across all log filesexport <fmt>Export all data (json, csv, or txt)search <term>Search across all log entriesrecentShow the 20 most recent activity log entriesstatusHealth check — version, entry count, disk usagehelpShow help with all available commandsversionPrint version string

How It Works#

Each domain command ( run, check, convert, etc.) works in two modes:

• Read mode (no arguments): displays the last 20 entries from its log file
• Write mode (with arguments): appends a timestamped YYYY-MM-DD HH:MM|<input> line to its log file and logs the action to history.log

The built-in utility commands ( stats, export <fmt>, search, recent, status) aggregate data across all log files for reporting and analysis.

Data Storage#

All data is stored locally in ~/.local/share/persona-forge/:

• Each command writes to its own log file (e.g., run.log, check.log, generate.log)
• history.log records all write operations with timestamps
• Export files are saved as export.json, export.csv, or export.txt
• No external network calls — everything stays on disk

Requirements#

• Bash 4+ with set -euo pipefail
• Standard Unix utilities: date, wc, du, grep, tail, sed, cat
• No external dependencies or package installations needed

When to Use#

1. Creating character profiles — use generate to log new persona ideas and run to execute creation workflows
2. Analyzing personality traits — record trait analysis with analyze and validation results with check
3. Comparing characters — use compare to track side-by-side persona evaluations and differences
4. Batch persona generation — log bulk character creation jobs with batch and review outputs with preview
5. Exporting character data — export all persona records to JSON, CSV, or TXT for use in writing tools or game engines

Examples#

bash

# Generate a new persona
persona-forge generate "林夜 — protagonist, 武侠 setting, INTJ personality"

# Run a creation workflow
persona-forge run "Full character sheet for 林夜: backstory + traits + relationships"

# Analyze personality traits
persona-forge analyze "林夜: 沉稳 85%, 机敏 90%, 孤傲 70% — INTJ archetype match"

# Check character consistency
persona-forge check "林夜 backstory vs personality: no contradictions found"

# Compare two characters
persona-forge compare "林夜 vs 萧无痕: opposing motivations, complementary skills"

# Preview a character card
persona-forge preview "林夜 RPG card: STR 14, DEX 18, INT 16, WIS 12"

# Batch process multiple personas
persona-forge batch "Generate 5 NPCs for Act 2 tavern scene"

# Log configuration
persona-forge config "Default world: 武侠, output format: markdown"

# Export all persona data to JSON
persona-forge export json

# Search for a character
persona-forge search 林夜

# View recent activity
persona-forge recent

# Check system status
persona-forge status

Output#

All commands return results to stdout. Redirect to a file if needed:

bash

persona-forge stats > persona-summary.txt
persona-forge export csv

---

Powered by BytesAgain | bytesagain.com | hello@bytesagain.com