CLI Reference

Getting Help

To see all available CLI commands and options, run:

uv run komodo --help

For help with a specific command:

uv run komodo <command> --help

Global Options

Flag	Description
`--version`, `-v`	Show the CLI version and exit
`--help`	Show help text and exit

Authentication

Start the OAuth 2.0 Device Authorization Flow. Opens your browser for authentication and stores your JWT and refresh token in ~/.komodo/credentials.

uv run komodo login

Flag	Description
`-E`, `--environment`	Target environment: `production` (default). `integration` and `development` require `komodo-internal-tools`

komodo jwt

Print the current JWT token for debugging or use with external tools.

uv run komodo jwt

Flag	Description
`-E`, `--environment`	Target environment

Account Management

komodo account set

Interactively select the active Komodo account from your available accounts.

uv run komodo account set

komodo account get

Print the currently selected account ID and slug.

uv run komodo account get

komodo account list

List all accounts you have access to.

uv run komodo account list

Service Principals

Manage service principal credentials for machine-to-machine (M2M) authentication. See the Authentication guide for usage.

komodo service-principal create

Create a new service principal. Returns the client_id and client_secret.

uv run komodo service-principal create --name "my-service" --description "My service principal"

Flag	Description
`--name`	Name for the service principal (required)
`--description`	Description (optional)

komodo service-principal list

List all service principals for the current account.

uv run komodo service-principal list

komodo service-principal delete

Delete a service principal by ID.

uv run komodo service-principal delete <SERVICE_PRINCIPAL_ID>

MCP Server

komodo mcp show-config

Generate the MCP server configuration JSON for your AI client. The output is automatically copied to your clipboard.

uv run komodo mcp show-config

Flag	Description
`--name`, `-n`	Custom server name (default: `komodo`)

See the MCP Server guide for full setup instructions.

komodo mcp run

Start the MCP server with STDIO transport. Typically started automatically by your AI client via the configuration from show-config.

uv run komodo mcp run

SQL Queries

komodo sql-execute

Execute a single SQL statement against your Snowflake warehouse and display the results in a formatted table.

uv run komodo sql-execute "SELECT column_name FROM INFORMATION_SCHEMA.COLUMNS LIMIT 10"

Flag	Description
`-E`, `--environment`	Target environment

komodo sql-shell

Start an interactive SQL shell for running multiple queries in a session. Type exit to quit. Errors in one statement do not exit the shell.

uv run komodo sql-shell

Flag	Description
`-E`, `--environment`	Target environment

komodo sql-diagnostics

Show diagnostic detail for a previously executed query: the error code and message, execution status, warehouse, and timing that Snowflake recorded. Use this to self-diagnose a failed query without contacting Komodo support.

uv run komodo sql-diagnostics <query-id>

Argument / Flag	Description
`query-id`	The Snowflake query ID (`sfqid`) to diagnose
`-E`, `--environment`	Target environment

The query ID is the sfqid attribute on the cursor after execute (cursor.sfqid), and is also included in surfaced error messages as Query ID: .... Diagnostics are backed by Snowflake’s INFORMATION_SCHEMA.QUERY_HISTORY, so the query must be within the history retention window and a database must be set on the connection.

Marmot

komodo marmot

Open Marmot in your browser, or chat with Marmot from the terminal.

Without flags, opens the Marmot web app:

uv run komodo marmot

With --chat / -c, sends a message to Marmot: the CLI creates a new analysis with a conversation in it, waits for the reply, and renders it in the terminal.

uv run komodo marmot -c "How many NSCLC patients were treated in 2025?"

When run in an interactive terminal, the CLI then keeps the session open so you can reply and continue the conversation in the same analysis — press Ctrl+C (or Ctrl+D) to end. At the end it prints a link to open the analysis in the Marmot web app, where the conversation can be resumed with full history.

Every chat creates a Marmot analysis, which owns the conversation and any files Marmot produces while working (queries, cohort definitions, reports). Those files can be read programmatically — see the MarmotApi SDK reference.

Flag	Description
`--chat`, `-c`	Message to send. Omit to open Marmot in the browser instead
`--url`	Override the Marmot URL (e.g. `https://marmot-staging.komodohealth.com`)
`-E`, `--environment`	Target environment

Plugin Management

komodo plugin install

Install a Komodo CLI plugin package. Without arguments, installs komodo-internal-tools from Komodo’s internal package registry.

uv run komodo plugin install

Flag	Description
`--package`	Specific package name to install
`--path`	Install from a local path

komodo plugin uninstall

Uninstall a plugin package.

uv run komodo plugin uninstall <PACKAGE_NAME>

komodo plugin list

List installed plugins and their registered CLI commands and MCP tools.

uv run komodo plugin list

Utility Commands

komodo docs

Open the Marmot Development Kit documentation in your browser.

uv run komodo docs

komodo feedback

Submit feedback about the Marmot Development Kit.

uv run komodo feedback

Beta Commands

Beta commands are accessed through the komodo beta subgroup:

uv run komodo beta --help

komodo beta cohort-exploration

Explore patient cohorts interactively using the Cohort API. This command provides a streamlined interface for rapid validation of clinical hypotheses via interactive prompts.

uv run komodo beta cohort-exploration

Features:

Simple mode — Guided prompts for diagnosis codes (ICD-10), procedure codes (CPT/HCPCS), and drug references (NDC)
Advanced mode — Build complex AND/OR/nested condition logic
Quick count — Fast approximate or exact distinct patient count
Comprehensive summary — Demographic breakdowns by time trends, gender, age, state, race/ethnicity, and mortality, plus top providers by member count (NPI) and estimated HCP/HCO totals
Full NPI breakdown (opt-in) — After choosing the comprehensive summary, optionally export the cohort to get member counts for every provider NPI (rendering, billing, or any-role attribution). The first run exports cohort data and can take a few minutes; re-runs hit the export cache. Results show the top 50 providers in the terminal and write the complete breakdown to a CSV file. Requires cohort-export permissions.

Supported parameters:

Diagnosis Code (ICD-10 format, e.g., C34%, C50.1)
Procedure Code (CPT/HCPCS format, e.g., 96413, J9271)
Drug Reference (NDC Code, e.g., 12345-6789-01)
Provider NPI (10-digit, e.g., 1234567890) — medical claims, prescriber, or pharmacy; filter a cohort by one or more providers (Advanced mode)
Time Duration (date range in mm/dd/yy format)

Options:

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

komodo beta data-ingestion

Bring your own data into a Komodo dataset interactively — from a file in your own S3 bucket or from a local file. Guided prompts pick an approved schema, show its columns for review, and submit the ingestion.

uv run komodo beta data-ingestion

What it does:

Ingest data from customer bucket — pick a registered ingest source, choose an approved BYOD schema (its columns are shown), then give the full s3://… path to the file. Komodo validates the schema and that the path belongs to the source, then submits the ingestion.
Ingest data from local path — upload a local file against an approved BYOD schema; no bucket or cross-account role needed.
Check ingestion status — look up a submitted ingestion by request id.

Ingestion runs asynchronously; the wizard prints the dataset and request ids so you can check the status until it reaches a terminal state. See the Ingest API reference for the underlying SDK and MCP tools.

Options:

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