CLI Tools

The CLI (khaos-tools) is the analysis engine behind Khaos Machine. It handles screenplay parsing, entity extraction, and AI-powered analysis. While the web dashboard and TUI call it automatically, you can also use it directly for scripting and automation.

Common Commands

Parse a Screenplay

khaos-tools parse --input screenplay.fountain --output ~/my-project

Parses a screenplay file and creates a KSPD project structure with extracted scenes, characters, and locations.

Run Analysis

khaos-tools bot analyze-scene ~/my-project \
  --scene scene-001 \
  --provider openai \
  --model gpt-4o

Analyze a single scene with the specified provider and model.

Batch Analysis

khaos-tools bot analyze-all-scenes ~/my-project \
  --provider ollama \
  --model qwen3:8b

Analyze all scenes in a project.

Query Entities

# List all characters
khaos-tools query characters ~/my-project

# List all scenes
khaos-tools query scenes ~/my-project

# List all locations
khaos-tools query locations ~/my-project

Check Version

khaos-tools --version

Supported Formats

The parser auto-detects format by file extension:

Extension	Format
.fountain	Fountain (industry standard)
.fdx	Final Draft XML
.sbx	ScriptBuilder XML
.md	Markdown
.pdf	PDF (requires pdftotext)
.txt	Plain text

Output

Analysis results are written to the project's analysis/ directory as JSON files, organized by provider and entity type:

my-project/analysis/openai/scenes/scene-001.json
my-project/analysis/ollama/characters/john-doe.json

Scripting

Combine CLI tools with shell scripts for automation:

#!/bin/bash
# Analyze a screenplay with multiple providers

PROJECT=~/my-project

for provider in ollama openai; do
    echo "Analyzing with $provider..."
    khaos-tools bot analyze-all-scenes "$PROJECT" \
        --provider "$provider" \
        --model auto
done