run.sh Command

Execute simulations using the Timepoint Pro run script

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:

quick

Run all quick-tier templates (~30s-2min, less than $0.05 each)

./run.sh quick

standard

Run all standard-tier templates (~2-5 min, $0.05-0.20)

./run.sh standard

comprehensive

Run all comprehensive templates (~5-15 min, $0.20-1.00)

./run.sh comprehensive

showcase

Run production-ready showcase scenarios

./run.sh showcase

Template Listing

View available templates with metadata:

./run.sh list

Terminal Output

================================================================================
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

Terminal Output

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

Basic

# 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