SDK & CLI

Gatewyse ships two internal client tools alongside the server: a typed TypeScript SDK (@ai-gateway/sdk) and a gatewyse CLI (@ai-gateway/cli). Both target the gateway’s OpenAI-compatible HTTP surface, have no runtime dependencies (they use the global fetch from Node 18+ / browsers), and are marked private — they are bundled tooling for use inside the monorepo and its deployments, not published to npm.

TypeScript SDK

@ai-gateway/sdk is a small typed client over the gateway’s OpenAI-compatible endpoints. Because it is a workspace-internal package, reference it via the monorepo workspace rather than an npm install:

package.json

{
  "dependencies": {
    "@ai-gateway/sdk": "workspace:*"
  }
}

Creating a client

The constructor takes a GatewyseClientOptions object:

Field	Type	Required	Description
baseUrl	string	yes	Gateway base URL (scheme + host, no trailing slash).
apiKey	string	yes	API key, sent as Authorization: Bearer <apiKey>.
fetch	typeof fetch	no	Custom fetch implementation for tests or non-global environments.

Both baseUrl and apiKey are validated in the constructor; a missing value throws immediately. If no global fetch is available and none is passed, the constructor throws as well.

import { GatewyseClient } from '@ai-gateway/sdk';

const client = new GatewyseClient({
  baseUrl: 'https://your-gateway.example.com',
  apiKey: 'aigw_sk_...',
});

chat(request)

POST /v1/chat/completions (non-streaming). Takes a ChatCompletionRequest and resolves to a ChatCompletionResponse.

const response = await client.chat({
  model: 'gpt-4o',
  messages: [
    { role: 'system', content: 'You are a helpful assistant.' },
    { role: 'user', content: 'Explain circuit breakers in one sentence.' },
  ],
  temperature: 0.7,
  maxTokens: 256,
});

console.log(response.choices[0].message.content);
console.log(response.usage?.total_tokens);

The SDK exposes a camelCase convenience field maxTokens, which it translates to the wire field max_tokens before sending. All other fields are passed through verbatim (the request type has an open [key: string]: unknown index signature, so any additional OpenAI-compatible parameter is accepted).

ChatCompletionRequest fields:

• model: string
• messages: ChatMessage[]
• temperature?: number
• maxTokens?: number (sent as max_tokens)
• stream?: false (streaming is not supported by this method)

ChatMessage is { role: 'system' | 'user' | 'assistant' | 'tool'; content: string; name?: string }.

ChatCompletionResponse returns id, model, a choices array ({ index, message, finish_reason }), and an optional usage object ({ prompt_tokens, completion_tokens, total_tokens }).

listModels()

GET /v1/models — the models available to the authenticated key. Resolves to { data: Array<{ id: string; object: string }> }.

const { data } = await client.listModels();
for (const model of data) {
  console.log(model.id);
}

Error handling

Non-2xx responses throw a GatewyseError, which carries the HTTP status, a message (taken from the response’s error.message when present, otherwise a generic status message), and the parsed response body:

import { GatewyseClient, GatewyseError } from '@ai-gateway/sdk';

try {
  await client.chat({ model: 'gpt-4o', messages: [{ role: 'user', content: 'hi' }] });
} catch (err) {
  if (err instanceof GatewyseError) {
    console.error(err.status, err.message, err.body);
  }
}

gatewyse CLI

@ai-gateway/cli provides the gatewyse binary. It is self-contained (global fetch, no runtime dependencies) and reads the gateway URL and API key from flags or environment variables. Like the SDK, it is a private workspace package — built with pnpm --filter @ai-gateway/cli build, which produces the gatewyse bin (dist/bin.js).

Connection options

Every command resolves the gateway connection from flags first, then environment:

Flag	Env var	Description
--url <baseUrl>	GATEWYSE_URL	Gateway base URL (trailing slash is stripped).
--key <apiKey>	GATEWYSE_API_KEY	API key, sent as Authorization: Bearer <apiKey>.

If no URL can be resolved, the CLI prints an error and exits with code 2. The API key is optional at the CLI level (omitting it simply sends no Authorization header).

export GATEWYSE_URL=https://your-gateway.example.com
export GATEWYSE_API_KEY=aigw_sk_...

gatewyse health

Calls GET /health and prints the raw response body. Exits 0 when the response is OK, 1 otherwise.

gatewyse health --url https://your-gateway.example.com

gatewyse models

Calls GET /v1/models (with the auth header when a key is set) and prints the raw response body.

gatewyse models

gatewyse chat --model <id> "<prompt>"

Calls POST /v1/chat/completions with a single user message built from the prompt. Requires --model <id> and a prompt (positional arguments are joined with spaces). Missing either one prints an error and exits with code 2.

gatewyse chat --model gpt-4o "Explain circuit breakers in one sentence."

Help and exit codes

Running gatewyse, gatewyse help, or gatewyse --help prints usage. An unknown command prints usage plus an error and exits 1. Exit codes: 0 success, 1 request failure / unknown command, 2 missing required input (no URL, or missing chat model/prompt).