# @starship-ci/client: The Official NPM Client Package for Starship Deployment Management

> Discover the @starship-ci/client, the official NPM package for programmatically deploying, managing, and verifying Starship multi-chain environments with Helm and Kubernetes.

- Repository: [Hyperweb/starship](https://github.com/hyperweb-io/starship)
- Tags: api-reference
- Published: 2026-03-03

---

**The `@starship-ci/client` package is the official Node.js/TypeScript SDK that provides a high-level programmatic façade for deploying, managing, and verifying Starship multi-chain environments through Helm and Kubernetes orchestration.**

The `@starship-ci/client` package serves as the canonical **NPM client package for Starship**, published under the `hyperweb-io/starship` repository. It abstracts the complexity of Helm chart operations and Kubernetes resource management into a unified JavaScript/TypeScript interface, enabling developers to programmatically script complete blockchain devnet lifecycles from initialization to teardown.

## Core Responsibilities of the Starship NPM Client

### Helm Repository and Chart Management

The client handles all Helm interactions required to install Starship. In [`packages/packages/client/src/client.ts`](https://github.com/hyperweb-io/starship/blob/main/packages/packages/client/src/client.ts), the `setupHelm()` method executes `helm repo add` and `helm repo update` to register the Starship chart repository ([source](https://github.com/hyperweb-io/starship/blob/main/packages/packages/client/src/client.ts#L77-L85)). The `deploy()` method then constructs and runs the `helm install` command, injecting chain-specific scripts from your [`starship.yaml`](https://github.com/hyperweb-io/starship/blob/main/starship.yaml) configuration to create the release ([source](https://github.com/hyperweb-io/starship/blob/main/packages/packages/client/src/client.ts#L97-L135)).

### Kubernetes Connectivity and Pod Lifecycle Monitoring

Before any deployment, `checkConnection()` validates that `kubectl` can reach the cluster by running `kubectl get nodes`, aborting immediately on failure ([source](https://github.com/hyperweb-io/starship/blob/main/packages/packages/client/src/client.ts#L56-L72)). During runtime, `waitForPods()` and `checkPodStatus()` poll pod states and track restart counts, failing fast if containers enter crash loops ([source](https://github.com/hyperweb-io/starship/blob/main/packages/packages/client/src/client.ts#L76-L98)). When teardown is required, `deleteHelm()` executes `helm delete` to remove the release cleanly ([source](https://github.com/hyperweb-io/starship/blob/main/packages/packages/client/src/client.ts#L43-L45)).

### Port Forwarding and Service Verification

The client automatically bridges local ports to deployed services through `startPortForward()`, which walks the loaded configuration and invokes `kubectl port-forward` for chains, relayers, explorers, and registries ([source](https://github.com/hyperweb-io/starship/blob/main/packages/packages/client/src/client.ts#L335-L417)). After deployment, `verify()` delegates to the verifier modules in `packages/packages/client/src/verifiers/` to execute HTTP-based health checks defined in `@starship-ci/types`, confirming all components are operational ([source](https://github.com/hyperweb-io/starship/blob/main/packages/packages/client/src/client.ts#L610-L644)).

## Installing and Configuring @starship-ci/client

Install the package from the NPM registry:

```bash
npm install @starship-ci/client

```

Initialize the client with your deployment parameters:

```typescript
import { StarshipClient } from '@starship-ci/client';

const client = new StarshipClient({
  name: 'my-demo',                     // Helm release name
  config: 'starship.yaml',             // Path to Starship config file
  repo: 'starship',
  repoUrl: 'https://hyperweb-io.github.io/starship/',
  chart: 'devnet',
  version: '1.8.0',
  namespace: 'starship-ns',            // optional K8s namespace
});

```

The constructor merges these values with sensible defaults defined in `defaultStarshipContext` ([source](https://github.com/hyperweb-io/starship/blob/main/packages/packages/client/src/client.ts#L35-L44)).

## Deploying and Managing Starship Clusters

### Starting a Full Deployment

Load your configuration and execute the complete orchestration sequence:

```typescript
client.loadConfig();      // parses YAML into `client.config`
await client.start();     // checks K8s → setupHelm → deploy → waitForPods → startPortForward

```

The `start()` method in [`packages/packages/client/src/client.ts`](https://github.com/hyperweb-io/starship/blob/main/packages/packages/client/src/client.ts) coordinates the entire lifecycle from dependency validation through port forwarding ([source](https://github.com/hyperweb-io/starship/blob/main/packages/packages/client/src/client.ts#L69-L75)).

### Verifying Service Health

Confirm that all deployed services are responding correctly:

```typescript
await client.verify();    // runs verifiers from @starship-ci/types

```

### Tearing Down Environments

Clean up all Kubernetes resources and Helm releases programmatically:

```typescript
await client.stop();      // stops port-forwards → records status → helm delete → waits for termination

```

## Low-Level API Access

For granular control over specific lifecycle stages, bypass the high-level orchestration:

```typescript
client.setup();           // only adds Helm repo & updates it
client.deploy();          // installs chart without waiting for pods

```

## Dependency Validation

Before executing any cluster operations, `checkDependencies()` validates that required external tools are installed. This method reads the `dependencies` array from [`packages/packages/client/src/deps.ts`](https://github.com/hyperweb-io/starship/blob/main/packages/packages/client/src/deps.ts)—which specifies `kubectl`, `docker`, and `helm`—and aborts with installation instructions if any binary is missing ([source](https://github.com/hyperweb-io/starship/blob/main/packages/packages/client/src/client.ts#L86-L112)).

## Summary

- The `@starship-ci/client` package provides the **official Node.js SDK** for managing Starship deployments via NPM.
- It abstracts **Helm chart operations**, **Kubernetes pod monitoring**, and **port forwarding** into a unified TypeScript interface.
- Key methods include `start()` for full deployment orchestration, `verify()` for health checks, and `stop()` for resource cleanup.
- The client validates dependencies and cluster connectivity before executing any operations to ensure reliable automation.
- Source code is located in `packages/packages/client/src/` within the `hyperweb-io/starship` repository.

## Frequently Asked Questions

### What is the difference between `start()` and `deploy()` in the Starship client?

The `start()` method is a high-level orchestrator that executes the complete lifecycle: checking Kubernetes connectivity, setting up Helm, deploying the chart, waiting for pods to be ready, and starting port forwards. In contrast, `deploy()` only constructs and executes the `helm install` command without waiting for pod readiness or setting up port forwarding, providing lower-level control for custom workflows.

### How does the client handle Kubernetes dependency checks?

Before any operation, `checkDependencies()` validates that `kubectl`, `docker`, and `helm` binaries are installed by referencing the `dependencies` array defined in [`src/deps.ts`](https://github.com/hyperweb-io/starship/blob/main/src/deps.ts). If any tool is missing, the client prints installation hints and aborts to prevent runtime failures during cluster operations.

### Can I use the client in CI/CD pipelines?

Yes. The package is designed for automated environments, allowing you to programmatically spin up multi-chain devnets in GitHub Actions, GitLab CI, or other pipelines. The `start()` and `stop()` methods provide deterministic deployment and cleanup, while `verify()` ensures services are healthy before proceeding to test steps.

### Where are the health check verifiers implemented?

Service verification logic resides in `packages/packages/client/src/verifiers/`, where individual modules implement HTTP-based health checks for specific components like chains, relayers, and explorers. The `verify()` method in [`client.ts`](https://github.com/hyperweb-io/starship/blob/main/client.ts) delegates to these verifiers and formats the results according to the type definitions in `@starship-ci/types`.