@gretl/sdk

Node.js SDK for Gretl — control local services by name or port number.

Gretl must be running for any of these calls to work. It exposes a local API on http://127.0.0.1:27892.

Install

npm install @gretl/sdk

Quick start

import { gr } from "@gretl/sdk";

// List all monitored ports
const ports = await gr.ports();

// Start a service and wait for it to be ready
await gr.start(3000);
await gr.waitForActive(3000);

// Stop it
await gr.stop(3000);

// Start/stop all services in a group
await gr.startGroup("backend");
await gr.stopGroup("backend");

API

gr.ports()

Returns all monitored ports with current status (active, pid, process, etc).

gr.port(port)

Get a single port by number. Throws if not found.

gr.start(port)

Start the service on the given port using its configured command.

gr.stop(port)

Kill the process currently listening on the given port.

gr.remove(port)

Remove a port from Gretl's watch list.

gr.active() / gr.inactive()

Filter to only running or stopped ports.

gr.statusGroup(group) / gr.startGroup(group) / gr.stopGroup(group)

Operate on all ports tagged with a group name.

gr.waitForActive(port, intervalMs?, timeoutMs?)

Poll until the port is active. Default timeout: 30s.

gr.waitForInactive(port, intervalMs?, timeoutMs?)

Poll until the port is inactive. Default timeout: 15s.

Kubernetes & cloud

gr.k8s exposes the Gretl cloud API for managing Kubernetes workloads. Set the GR_TOKEN environment variable or pass a token when constructing GretlClientWithK8s.

import { gr } from "@gretl/sdk";
// GR_TOKEN is read automatically from process.env

// List clusters and workloads
const clusters = await gr.k8s.clusters();
const workloads = await gr.k8s.workloads(clusters[0].id);

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

// Tether a port to a public tunnel URL
const tether = await gr.k8s.tether(workloads[0].id, 8000);
console.log(tether.tunnel_url);

// Force a cluster sync
await gr.k8s.sync(clusters[0].id);

// Configure auto-sleep
await gr.k8s.setAutoSleep(workloads[0].id, true, 30);

K8s methods

| Method | Description | |---|---| | gr.k8s.clusters() | List connected clusters | | gr.k8s.workloads(clusterId?) | List workloads, optionally filtered by cluster | | gr.k8s.sync(clusterId) | Force a cluster sync | | gr.k8s.sleep(workloadId) | Scale workload to zero | | gr.k8s.wake(workloadId) | Restore replicas | | gr.k8s.tether(workloadId, port, label?) | Create a public tunnel to a container port | | gr.k8s.detach(tetherId) | Deactivate a tether | | gr.k8s.tethers() | List active tethers | | gr.k8s.autoSleep(workloadId) | Get auto-sleep config | | gr.k8s.setAutoSleep(workloadId, enabled, idleTimeoutMinutes) | Update auto-sleep config |

CI / GitHub Actions

Use the official GitHub Actions instead of the SDK for CI pipelines:

- uses: gretl-sdks/actions/wake@v1
  with:
    token: ${{ secrets.GRETL_TOKEN }}
    server: my-server

See gretl-sdks/actions for wake and sleep actions.

Links

• gretl.dev
• Docs
• REST API reference
• CLI: @gretl/cli
• GitHub