Cohort CLI Reference

The Cohort Exploration CLI provides an interactive interface for rapid validation of clinical hypotheses. Build complex cohort queries with AND/OR logic and get patient counts with demographic breakdowns.

Prerequisites

Install the Komodo SDK
Authenticate:
Terminal window
```
uv run komodo login -E integration
```

Set your account:

uv run komodo account set -E integration

Usage

Start Interactive Exploration

Launch the interactive cohort exploration tool:

uv run komodo alpha cohort-exploration -E integration

Options

Option	Description
`--environment, -E`	Target environment (default: production)

Query Modes

Simple Mode

Guided prompts for common fields. All conditions are combined with AND logic.

Diagnosis Code(s) - ICD-10 format (e.g., C34%, C50.1)
Procedure Code(s) - CPT/HCPCS format (e.g., 96413, J9271)
Drug Reference(s) - NDC format (e.g., 12345678901)

Enter multiple values separated by commas for OR logic within each field.

Advanced Mode

Build complex queries with nested AND/OR logic:

Add individual conditions
Create nested condition groups
Change the root operator (AND/OR)
Remove conditions as needed

Supported Selector Types

Selector	Description	Examples
`mx_diagnosis_code`	ICD-10 diagnosis codes	`C34%`, `C50.1`, `Z51.11`
`cpt_hcpcs_code`	CPT/HCPCS procedure codes	`96413`, `99213`, `J9271`
`ndc`	National Drug Codes	`12345678901`, `12345-6789-01`
`drg_code`	Diagnosis Related Group codes	`470`, `871`
`revenue_code`	Revenue codes	`0636`, `0250`

Wildcard Matching

Use the % suffix for prefix matching:

C34% matches C34, C34.1, C34.9, etc.
964% matches 96413, 96415, 96417, etc.

Output Modes

Quick Count

Get just the total patient count (faster):

📊 Quick count - just the total patient count

Comprehensive Summary

Get detailed demographic breakdowns with visualizations:

📈 Comprehensive summary - demographics, trends, bar charts

Includes:

Total patient count
Trend by year and quarter
Gender distribution
Age distribution
Top 10 US states (with option to add more)
Race/ethnicity breakdown
Mortality statistics

Count Types

Type	Description
Approximate	Fast approximate count for quick exploration
Distinct	Exact distinct patient count (requires date range)

Date Range

Date ranges use mm/dd/yy format:

Start Date: Required for comprehensive summary or distinct counts
End Date: Optional (defaults to today)

Example Session

┌─────────────────────────────────────────────────────────────────────┐
│ 🔬 Cohort API Query Builder                                          │
│                                                                      │
│ Build complex cohort queries with AND/OR logic.                     │
│ • Add conditions one at a time                                       │
│ • Combine conditions with AND or OR                                  │
│ • Create nested groups for complex logic                            │
│ • Use % suffix for prefix matching                                   │
└─────────────────────────────────────────────────────────────────────┘

? Query mode: Simple - guided prompts for common fields

  💡 Enter comma-separated values for OR logic within each field.
  💡 All fields are combined with AND logic.

? Diagnosis Code(s) (ICD-10, e.g., C34%,C50%): C34%
? Procedure Code(s) (CPT/HCPCS, e.g., 96413,96415): 96413,96415
? Drug Reference(s) (NDC, e.g., 12345678901):

Query (AND logic)
├── 1. Diagnosis Code (ICD-10): C34%
└── 2. Procedure Code (CPT/HCPCS): 96413 OR 96415

? What output would you like? 📈 Comprehensive summary
? Count type for total patients: ⚡ Approximate (fast)
? Start Date (mm/dd/yy): 01/01/23
? End Date (mm/dd/yy): 12/31/25

State Filtering

By default, the comprehensive summary queries the top 10 US states by population:

FL, CA, NY, TX, PA, OH, IL, MI, NC, GA

You can optionally add specific state codes:

? Add specific state codes to query? Yes
? Additional State Codes: AZ, NV, WA, CO
  ✅ Added states: AZ, NV, WA, CO

Error Handling

Common errors and solutions:

Error	Solution
”No access token found”	Run `komodo login` to authenticate
”Access denied”	Contact your administrator for cohort API access
”Date range required”	Provide a date range for distinct counts or comprehensive summary
”Invalid format”	Check code format matches the selector type examples