Skip to main content
The run.sh script is the single entry point for all Timepoint Pro simulation operations.

​
Quick Start

# List all available templates
./run.sh list

# Run a single template
./run.sh run board_meeting

# Run by tier
./run.sh quick

# Show recent runs
./run.sh status

​
Basic Usage

./run.sh <command> [options]
./run.sh <preset>              # Quick shortcuts
./run.sh <template_name>       # Direct template execution

​
Run Command

Execute simulations with the run command: 
./run.sh run [TEMPLATE|PRESET] [OPTIONS]

​
Selection Options

​
--template
string
Run a specific template by name
./run.sh run --template board_meeting
# Or use shortcut:
./run.sh run board_meeting
​
--tier
string
Filter by complexity tier: quick, standard, or comprehensive
./run.sh run --tier quick
​
--category
string
Filter by category: showcase, persona, or convergence
./run.sh run --category showcase
​
--mechanism
string
Filter by mechanism tags (comma-separated)
./run.sh run --mechanism M1,M7,M11

​
Execution Options

​
--parallel
number
default:"1"
Run N templates concurrently
./run.sh run --tier quick --parallel 4
​
--dry-run
boolean
Show cost estimate without running
./run.sh run board_meeting --dry-run
​
--skip-summaries
boolean
Skip LLM summary generation (faster, cheaper)
./run.sh run quick --skip-summaries
​
--budget
number
Stop if cost exceeds budget (USD)
./run.sh run --category showcase --budget 5.00

​
Model Options

​
--model
string
Override LLM model for all calls
./run.sh run board_meeting --model deepseek/deepseek-chat
​
--free
boolean
Use best quality free model ($0 cost)
./run.sh run --free board_meeting
​
--free-fast
boolean
Use fastest free model ($0 cost)
./run.sh run --free-fast quick
​
--gemini-flash
boolean
Use Google Gemini 3 Flash (1M context, fast inference)
./run.sh run --gemini-flash board_meeting
​
--groq
boolean
Use Groq Llama 3.3 70B (~300 tok/s, best quality)
./run.sh run --groq board_meeting
Requires GROQ_API_KEY in .env
​
--fast
boolean
Use Mixtral 8x7B (~200 tok/s, fastest)
./run.sh run --fast quick

​
Presets

Quick shortcuts for running template groups:
Run all quick-tier templates (~30s-2min, less than $0.05 each)
./run.sh quick

​
Template Listing

View available templates with metadata: 
./run.sh list

================================================================================
TEMPLATE CATALOG
================================================================================
ID                                       TIER           CATEGORY     MECHANISMS
--------------------------------------------------------------------------------
showcase/board_meeting                   standard       showcase     M1, M7, M11, M13
showcase/jefferson_dinner                standard       showcase     M3, M7, M11, M13
showcase/hospital_crisis                 standard       showcase     M8, M14
showcase/detective_prospection           standard       showcase     M15, M7
showcase/kami_shrine                     standard       showcase     M16
showcase/sec_investigation               comprehensive  showcase     M3, M7, M19
showcase/castaway_colony_branching       comprehensive  showcase     M1-M19 (all)
convergence/simple                       quick          convergence  M7, M11
convergence/standard                     standard       convergence  M7, M11, M13
...
--------------------------------------------------------------------------------
Total: 21 templates

​
Filter by Category

# Show only showcase templates
./run.sh list --category showcase

# Show only convergence tests
./run.sh list --category convergence

# Show only quick tier
./run.sh list --tier quick

​
List Patches

View template patches from SYNTH.md: 
# List all patch categories
./run.sh list patches

# List patches in specific category
./run.sh list patches corporate
./run.sh list patches historical
./run.sh list patches crisis
Available patch categories:
  • corporate - Business/startup scenarios
  • historical - Historical events
  • crisis - High-stakes emergency scenarios
  • mystical - Spiritual/animistic scenarios
  • mystery - Detective/investigation scenarios
  • mechanism - Core mechanism isolation tests
  • portal - Backward reasoning scenarios
  • stress - High-complexity stress tests
  • convergence - Consistency evaluation tests

​
Portal Testing Modes

Backward reasoning from known outcomes:
​
--portal-all
boolean
Run all portal testing modes
​
--portal-test-only
boolean
Basic portal test
​
--portal-simjudged-quick
boolean
Quick simjudged portal (5 steps)
​
--portal-simjudged
boolean
Standard simjudged portal
​
--portal-simjudged-thorough
boolean
Thorough simjudged portal (10 steps, ~$0.50-1.00, 60-90 min)
# Quick portal demo
./run.sh run --portal-quick board_meeting

# All portal modes
./run.sh run --portal-all

# Thorough backward reasoning
./run.sh run --portal-simjudged-thorough mars_mission_portal

​
Convergence Testing

Run templates multiple times to test consistency:
​
--convergence
boolean
Run convergence analysis after execution
​
--convergence-runs
number
default:"3"
Number of runs for analysis
​
--convergence-e2e
boolean
Run template N times + analyze
# Run template 3 times and analyze
./run.sh run --convergence-e2e board_meeting

# Run 5 times
./run.sh run --convergence-e2e --convergence-runs 5 convergence_simple

# View convergence history
./run.sh convergence history

​
Natural Language Mode

Generate simulations from natural language descriptions:
​
--nl
string
Natural language simulation prompt
​
--nl-entities
number
default:"4"
Number of entities to generate
​
--nl-timepoints
number
default:"3"
Number of timepoints to generate
# Generate from prompt
./run.sh run --nl "emergency board meeting about merger"

# Specify entity and timepoint count
./run.sh run --nl "detective interrogates 3 witnesses" --nl-entities 4 --nl-timepoints 5

​
Status and Export

​
View Run Status

# Show latest run
./run.sh status

# Show specific run
./run.sh status run_20241207_123456

# Show full details
./run.sh status --full

Run ID:     run_20241207_123456
Status:     completed
Template:   board_meeting
Started:    2024-12-07 12:34:56
Duration:   127s
Cost:       $0.0234
Tokens:     1,245
LLM Calls:  15
Entities:   4
Timepoints: 3

​
Export Results

# Export latest run as markdown
./run.sh export last

# Export as JSON
./run.sh export last --format json

# Export specific run
./run.sh export run_20241207_123456 --output ./results

​
API Mode

Submit jobs via REST API:
​
--api
boolean
Submit via REST API
​
--api-url
string
default:"http://localhost:8080"
API base URL
​
--api-key
string
API authentication key
​
--api-wait
boolean
Wait for job completion
# Start API server
./run.sh dashboard

# Submit via API
./run.sh run --api board_meeting

# Submit and wait
./run.sh run --api --api-wait --api-key your_key board_meeting

​
Examples

# Run single template
./run.sh board_meeting

# Run by tier with parallelism
./run.sh run --tier quick --parallel 4

# Run by category
./run.sh run --category showcase

​
Next Steps

Training

Train entities with historical context

Interactive Queries

Query simulation results

Evaluation

Understand evaluation metrics

CLI Overview

Back to CLI overview

Build docs developers (and LLMs) love

Get started for freeTalk to us