CLI Usage

The opql command-line tool provides direct access to PQL functionality from the terminal, making it easy to run poker calculations and analysis without writing Rust code.

Installation

Install the CLI tool using Cargo:

cargo install opql

Or build from source:

git clone https://github.com/solve-poker/open-pql.git
cd open-pql
cargo build --release --bin opql

Basic Usage

The basic syntax is:

opql [OPTIONS] -c "PQL_QUERY"

Simple Examples

# Basic equity calculation
opql -c "select equity from hero='AhKh', villain='QQ', game='holdem'"

# Average board suit count
opql -c "select avg(boardsuitcount(river)) from hero='As9s', villain='*', board='2s3sJh', game='holdem'"

# Hand type probability
opql -c "select avg(handtype(flop) = 'pair') from hero='AhKh', game='holdem'"

Command-Line Options

-c, --command <QUERY>

Execute a single PQL query and exit.

opql -c "select equity from hero='AK', villain='QQ', game='holdem'"

-f, --file <FILE>

Read and execute PQL queries from a file.

# Create a file with queries
echo "select equity from hero='AA', villain='KK', game='holdem'" > queries.pql
echo "select equity from hero='AK', villain='QQ', game='holdem'" >> queries.pql

# Execute queries from file
opql -f queries.pql

-o, --output <FORMAT>

Specify output format (default: table).

# Table format (default)
opql -c "select equity from hero='AA', villain='KK', game='holdem'" -o table

# JSON format
opql -c "select equity from hero='AA', villain='KK', game='holdem'" -o json

# CSV format
opql -c "select equity from hero='AA', villain='KK', game='holdem'" -o csv

-v, --verbose

Enable verbose output for debugging.

opql -v -c "select equity from hero='AA', villain='KK', game='holdem'"

--help

Show help information and available options.

opql --help

Interactive Mode

Run opql without arguments to enter interactive mode:

opql

In interactive mode, you can:

• Enter multiple queries
• Use command history
• Exit with quit or Ctrl+D

> select equity from hero='AA', villain='KK', game='holdem'
0.817

> select avg(handtype(flop) = 'three_of_a_kind') from hero='AA', game='holdem'
0.118

> quit

Advanced Examples

Multi-Player Scenarios

# Three-way all-in
opql -c "select equity from hero='AA', villain1='KK', villain2='QQ', game='holdem'"

# Position-based ranges
opql -c "select equity from hero='22+,A2+', button='*', sb='*', bb='88+,AJ+', game='holdem'"

Complex Queries

# Conditional equity
opql -c "select avg(equity) from hero='AhKh', villain='QQ' where boardsuitcount(flop) >= 2, game='holdem'"

# Range vs range analysis
opql -c "select equity from hero='JJ+,AK', villain='22+,A7+,K9+', game='holdem'"

File-Based Analysis

Create a file analysis.pql:

-- Preflop equity analysis
select equity from hero='AA', villain='KK', game='holdem';
select equity from hero='AK', villain='QQ', game='holdem';
select equity from hero='22', villain='AK', game='holdem';

-- Postflop scenarios  
select equity from hero='AA', villain='KK', board='A72', game='holdem';
select equity from hero='AA', villain='KK', board='K72', game='holdem';

Run the analysis:

opql -f analysis.pql -o table

Output Formats

Table Format (Default)

┌────────────┬────────┐
│ Query      │ Result │
├────────────┼────────┤
│ equity     │ 0.817  │
└────────────┴────────┘

JSON Format

{
  "results": [
    {
      "query": "select equity from hero='AA', villain='KK', game='holdem'",
      "result": 0.817,
      "execution_time_ms": 15
    }
  ]
}

CSV Format

query,result,execution_time_ms
"select equity from hero='AA', villain='KK', game='holdem'",0.817,15

Performance Tips

Optimize Queries

# Slow: Average over all possible boards
opql -c "select avg(equity) from hero='AA', villain='KK', game='holdem'"

# Fast: Specific board
opql -c "select equity from hero='AA', villain='KK', board='A72r', game='holdem'"

Use Appropriate Ranges

# Reasonable range size
opql -c "select equity from hero='88+,AJ+', villain='22+,A7+', game='holdem'"

# Very large computation (will be slow)
opql -c "select avg(equity) from hero='*', villain='*', game='holdem'"

Error Handling

Common errors and solutions:

Syntax Errors

# Invalid syntax
opql -c "select equity from hero='AA' villain='KK', game='holdem'"
# Error: Expected ',' after hero specification

# Correct syntax
opql -c "select equity from hero='AA', villain='KK', game='holdem'"

Invalid Hands

# Invalid card
opql -c "select equity from hero='AZ', villain='KK', game='holdem'"
# Error: Invalid card 'AZ'

# Correct format
opql -c "select equity from hero='As', villain='KK', game='holdem'"

Range Errors

# Invalid range
opql -c "select equity from hero='ZZ+', villain='KK', game='holdem'"
# Error: Invalid range 'ZZ+'

# Correct range
opql -c "select equity from hero='22+', villain='KK', game='holdem'"

Scripting and Automation

Batch Processing

#!/bin/bash
# analyze_hands.sh

hands=("AA" "KK" "QQ" "JJ" "AK" "AQ")
villain="22+,A7+,K9+"

for hand in "${hands[@]}"; do
    echo "Analyzing $hand vs $villain"
    opql -c "select equity from hero='$hand', villain='$villain', game='holdem'"
done

Output Processing

# Extract numeric results
opql -c "select equity from hero='AA', villain='KK', game='holdem'" -o csv | tail -n +2 | cut -d, -f2

# Compare multiple scenarios
for board in "A72r" "K72r" "Q72r"; do
    result=$(opql -c "select equity from hero='AA', villain='KK', board='$board', game='holdem'" -o csv | tail -n +2 | cut -d, -f2)
    echo "Board $board: $result"
done

Integration Examples

GTO Study Sessions

# Create study scenarios
cat > gto_study.pql << EOF
-- Button vs BB 3-bet scenarios
select equity from hero='22+,A2+,K5+,Q8+', villain='88+,AJ+,KQ+', game='holdem';

-- Short stack push/fold
select equity from hero='22+,A2+,K7+,Q9+', villain='88+,AJ+', game='holdem';

-- Flop continuation betting
select avg(equity) from hero='AK', villain='22+' where board_suit_count(flop) = 3, game='holdem';
EOF

opql -f gto_study.pql

Tournament Analysis

# ICM pressure scenarios
opql -c "select equity from hero='A7o', villain='66+,A8+,KJ+', game='holdem'"
opql -c "select equity from hero='K9s', villain='44+,A5+,KT+', game='holdem'"
opql -c "select equity from hero='Q8s', villain='22+,A2+,K8+', game='holdem'"

The CLI tool provides a powerful interface for poker analysis, suitable for both quick calculations and comprehensive study sessions.