Metadata-Version: 2.4
Name: gretl
Version: 1.1.0
Summary: Python SDK for Gretl — control local services by name or port number
Author-email: Gretl <info@gretl.dev>
License: MIT
Project-URL: Homepage, https://gretl.dev
Project-URL: Documentation, https://gretl.dev/docs.html
Project-URL: Repository, https://github.com/slowdutch/Gretl
Keywords: port,localhost,devtools,service-manager
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# gretl

Python SDK for [Gretl](https://gretl.dev) — control local services by name or port number.

## Install

```bash
pip install gretl
```

## Quick start

```python
from gretl import gr

# List all monitored ports
ports = gr.ports()

# Start / stop by name or port number
gr.start("api")
gr.stop("3000")

# Start / stop an entire group
gr.start_group("backend")
gr.stop_group("backend")

# Wait for a service to come up (useful in tests)
gr.wait_for_active("postgres", timeout=30)

# Add a new port to monitoring
gr.add(7401, name="jobs-server", cmd="node jobs.js", group="backend")
```

## API

| Method | Description |
|---|---|
| `gr.ports()` | Return all monitored ports |
| `gr.port(query)` | Find ports by name substring or exact port number |
| `gr.active()` | Only running ports |
| `gr.inactive()` | Only stopped ports |
| `gr.start(query)` | Start matching service(s) |
| `gr.stop(query)` | Stop matching service(s) |
| `gr.remove(query)` | Remove from monitoring |
| `gr.start_group(group)` | Start all ports in a group |
| `gr.stop_group(group)` | Stop all ports in a group |
| `gr.status_group(group)` | List all ports in a group |
| `gr.wait_for_active(query, timeout, interval)` | Block until active |
| `gr.wait_for_inactive(query, timeout, interval)` | Block until inactive |
| `gr.add(port, name, cmd, group, cwd)` | Register a new port |

## Kubernetes & cloud

`gr.k8s` exposes the Gretl cloud API for managing Kubernetes workloads. Set `GR_TOKEN` in your environment or pass `token=` to `GretlClient`.

```python
from gretl import gr
# GR_TOKEN is read automatically from os.environ

clusters = gr.k8s.clusters()
workloads = gr.k8s.workloads(cluster_id=clusters[0]["id"])

# Sleep / wake a workload
gr.k8s.sleep(workloads[0]["id"])
gr.k8s.wake(workloads[0]["id"])

# Tether a container port to a public tunnel URL
tether = gr.k8s.tether(workloads[0]["id"], container_port=8000)
print(tether["tunnel_url"])

# Force a cluster sync
gr.k8s.sync(clusters[0]["id"])

# Configure auto-sleep
gr.k8s.set_auto_sleep(workloads[0]["id"], enabled=True, idle_timeout_minutes=30)
```

| Method | Description |
|---|---|
| `gr.k8s.clusters()` | List connected clusters |
| `gr.k8s.workloads(cluster_id=None)` | List workloads |
| `gr.k8s.sync(cluster_id)` | Force cluster sync |
| `gr.k8s.sleep(workload_id)` | Scale to zero |
| `gr.k8s.wake(workload_id)` | Restore replicas |
| `gr.k8s.tether(workload_id, container_port, label=None)` | Create public tunnel |
| `gr.k8s.detach(tether_id)` | Deactivate a tether |
| `gr.k8s.tethers()` | List active tethers |
| `gr.k8s.auto_sleep(workload_id)` | Get auto-sleep config |
| `gr.k8s.set_auto_sleep(workload_id, enabled, idle_timeout_minutes)` | Update auto-sleep config |

## Requirements

The Gretl daemon must be running for local port methods. Download free at [gretl.dev](https://gretl.dev). K8s methods require a `GR_TOKEN` from your Gretl dashboard.

## Links

- [gretl.dev](https://gretl.dev)
- [GitHub](https://github.com/slowdutch/Gretl)
- [npm SDK: @gretl/sdk](https://www.npmjs.com/package/@gretl/sdk)
- [RubyGems: gretl](https://rubygems.org/gems/gretl)
