Metadata-Version: 2.4
Name: trinops
Version: 0.4.0
Summary: Trino query monitoring: CLI, TUI dashboard, and progress library
Project-URL: Homepage, https://github.com/lokkju/trinops
Project-URL: Repository, https://github.com/lokkju/trinops
Project-URL: Issues, https://github.com/lokkju/trinops/issues
Author-email: Loki Coyote <loki@lokkju.com>
License-Expression: LicenseRef-PolyForm-Shield-1.0.0
License-File: LICENSE
Keywords: cli,monitoring,queries,trino,tui
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Database
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.10
Requires-Dist: keyring>=23.0
Requires-Dist: rich>=13.0
Requires-Dist: textual>=0.40
Requires-Dist: tomlkit>=0.12
Requires-Dist: trino>=0.320
Requires-Dist: typer>=0.9
Provides-Extra: tqdm
Requires-Dist: tqdm>=4.60; extra == 'tqdm'
Description-Content-Type: text/markdown

# trinops

[![CI](https://github.com/lokkju/trinops/actions/workflows/test.yml/badge.svg)](https://github.com/lokkju/trinops/actions/workflows/test.yml)
[![PyPI](https://img.shields.io/pypi/v/trinops)](https://pypi.org/project/trinops/)
[![Python](https://img.shields.io/pypi/pyversions/trinops)](https://pypi.org/project/trinops/)
[![License](https://img.shields.io/badge/license-PolyForm%20Shield-blue)](https://polyformproject.org/licenses/shield/1.0.0/)

Trino query monitoring from the terminal. CLI commands for listing and inspecting queries, a live TUI dashboard, and a progress-tracking library for use in Python scripts.

**[Documentation →](https://trino.ps)**

<p align="center">
  <img src="https://raw.githubusercontent.com/lokkju/trinops/main/docs/screenshots/hero.gif" alt="trinops TUI dashboard" width="100%">
</p>

## Installation

Try it without installing:

```bash
uvx trinops top
```

Or install permanently:

```bash
pip install trinops
```

For tqdm progress bars in library usage:

```bash
pip install trinops[tqdm]
```

## Quick Start

Point at a cluster and go:

```bash
trinops top --server trino.example.com --user myuser
```

Or configure once and skip the flags:

```bash
trinops config init --server trino.example.com --user myuser --auth none --yes
trinops top
```

Environment variables work too:

```bash
export TRINOPS_SERVER=trino.example.com
export TRINOPS_USER=myuser
trinops top
```

## CLI Usage

### List queries

```bash
# Your recent queries
trinops queries

# All users' queries
trinops queries --query-user all

# Filter by state
trinops queries --state RUNNING

# JSON output (pipe to jq, etc.)
trinops queries --json

# Select specific fields
trinops queries --select query_id,state,user,elapsed_time
```

### Inspect a single query

```bash
# Rich formatted detail
trinops query <query-id>

# Full REST API response as JSON
trinops query <query-id> --json

# Select specific fields from the raw response
trinops query <query-id> --select queryId,state,queryStats.elapsedTime,queryStats.peakUserMemoryReservation
```

### Schema search

Cache catalog metadata locally and search across tables and columns:

```bash
# Cache a specific catalog
trinops schema refresh --catalog tpch

# Cache all discoverable catalogs
trinops schema refresh --all

# Search for tables
trinops schema search "lineitem"
trinops schema search "order*"

# Search for columns
trinops schema search --columns "customer_id"

# Show table details
trinops schema show tpch.sf1.lineitem

# List cached catalogs
trinops schema list
```

All schema commands support `--json` output and `--profile` for multi-cluster setups.

### TUI dashboard

```bash
trinops tui
trinops top  # alias
```

The dashboard shows a live-updating table of queries with sorting, a tabbed detail pane, and configurable refresh interval.

Keybindings:

| Key | Action |
|-----|--------|
| `r` | Force refresh |
| `u` | Toggle user filter |
| `a` | Show all users |
| `-` / `+` | Adjust refresh interval |
| `Enter` | Open detail pane for selected query |
| `Escape` | Close detail pane |
| `k` | Kill selected query (when enabled) |
| `Tab` / `Shift+Tab` | Cycle focus between table and detail pane |
| `q` | Quit |

When the detail pane is open:

| Key | Action |
|-----|--------|
| `Up` / `Down` | Scroll tab content |
| `Left` / `Right` | Switch between tabs |
| `PgUp` / `PgDn` | Page scroll |
| `Home` / `End` | Jump to top/bottom |
| `c` | Copy current tab content to clipboard |

Click column headers to sort; click again to reverse. Default sort is by Elapsed time, descending.

## Configuration

Config file lives at `~/.config/trinops/config.toml`:

```toml
[default]
server = "trino.example.com"
scheme = "https"
user = "myuser"
auth = "none"
query_limit = 50

[profiles.prod]
server = "trino-prod.example.com:443"
auth = "oauth2"
```

Manage config from the CLI:

```bash
# Set individual values
trinops config set server trino.example.com
trinops config set user myuser
trinops config set query_limit 100

# Configure a named profile
trinops config set server trino-prod:443 --profile prod
trinops config set auth oauth2 --profile prod

# View current config
trinops config show
trinops config show --profile prod
```

### Authentication

Supported methods: `none`, `basic`, `jwt`, `oauth2`, `kerberos`.

```bash
# Check auth status
trinops auth status

# Run OAuth2 flow
trinops auth login
```

For `basic` auth, use `password_cmd` to fetch credentials from a secret manager (e.g., `pass`, `1password-cli`) rather than storing passwords in the config file. For `oauth2`, install `keyring` to cache tokens across sessions.

## Library Usage

Wrap a trino cursor or connection to get live progress display during query execution:

```python
import trino
from trinops import TrinoProgress

conn = trino.dbapi.connect(host="trino.example.com", port=443, user="myuser")
cursor = conn.cursor()

with TrinoProgress(cursor) as tp:
    tp.execute("SELECT * FROM catalog.schema.table")
    rows = tp.fetchall()
```

You can also monitor an already-running query by passing a connection and query ID:

```python
with TrinoProgress(conn, query_id="20260310_143549_08022_abc") as tp:
    tp.start()
    tp.wait()
```

## Claude Code Integration

trinops ships with a [Claude Code skill](skills/trinops/SKILL.md) that teaches Claude how to query and inspect Trino cluster activity. If you have trinops installed in a project, Claude can use `trinops queries --select` and `trinops query <id> --select` to investigate query performance, find long-running queries, and diagnose failures with minimal context usage.

A [Claude Code plugin](/.claude-plugin/plugin.json) is also included for marketplace discoverability.

## Roadmap

Completed:

- ~~**Kill query support**~~ — cancel running queries from CLI and TUI ([#1](https://github.com/lokkju/trinops/issues/1))
- ~~**Enriched TUI detail**~~ — tabbed detail view with overview, stats, tables, and errors ([#2](https://github.com/lokkju/trinops/issues/2))
- ~~**Schema cache and search**~~ — cache catalog metadata locally, search tables/columns ([#3](https://github.com/lokkju/trinops/issues/3))

Planned:

- **Query plan visualization** — render the stage tree from the REST API in both CLI and TUI ([#5](https://github.com/lokkju/trinops/issues/5))
- **MCP server** — Model Context Protocol server for AI assistant integration ([#4](https://github.com/lokkju/trinops/issues/4))
- **Multi-cluster support** — switch between profiles in the TUI, unified multi-cluster view ([#6](https://github.com/lokkju/trinops/issues/6))
- **Notifications and alerts** — desktop notifications and webhooks for long-running queries and failures ([#7](https://github.com/lokkju/trinops/issues/7))
- **Worker/node health** — cluster node monitoring via `/v1/node` ([#8](https://github.com/lokkju/trinops/issues/8))

## Requirements

- Python 3.10+
- A running Trino cluster with the REST API accessible

## License

[PolyForm Shield 1.0.0](https://polyformproject.org/licenses/shield/1.0.0/)
