@clicloud/sdk

The typed TypeScript SDK for CLI Cloud deployment and remote-agent automation. Use it in applications, scripts, and agent runtimes that need a stable programmatic interface to CLI Cloud.

npm install @clicloud/sdk

import { createCliCloudClient } from "@clicloud/sdk";

const cliCloud = createCliCloudClient({
  apiKey: process.env.CLI_CLOUD_API_KEY,
});

const capabilities = await cliCloud.api.getCapabilities();
console.log(capabilities);

The SDK owns typed transport, route, lifecycle-response, and runtime-stream contracts. It defaults to CLI Cloud's public API; pass baseUrl only for a self-hosted, preview, or local environment. For interactive and shell automation, install @clicloud/cli and run clicloud.

Provider-neutral AI gateway

Use cliCloud.aiGateway (also available as cliCloud.api.aiGateway) for the platform-owned non-streaming AI gateway. Supply the provider credential only at request time; provider hosts and routing remain behind CLI Cloud.

const response = await cliCloud.aiGateway.chatCompletions({
  provider: "openai",
  providerApiKey: process.env.OPENAI_API_KEY!,
  idempotencyKey: crypto.randomUUID(),
  body: {
    model: "model-id",
    messages: [{ role: "user", content: "Hello" }],
  },
});

The client also exposes getOpenApiDocument(), listModels(), getRequestStatus(idempotencyKey), responses(), and messages(). Prefer secret-manager or environment injection for provider credentials; do not put raw keys in agent/MCP transcripts. Streaming is intentionally rejected until separately supported by the gateway capability profile. Unknown transport outcomes are durably fenced and must be read back/reconciled rather than automatically retried.

Source network routing

Source preview and materialization share one network contract across images, manifests, repositories, and archives:

• Omit network to request automatic public routing only when one safe listener is proven.
• Set network.ingress=false to keep the workload private. This explicit choice remains authoritative even when source evidence declares ports.
• Missing or ambiguous listener evidence returns network_port_required with candidatePorts; choose the application port and retry with an explicit network contract.

await cliCloud.api.previewSourceDeploymentPlan({
  kind: "image",
  image: "nginx:1.27-alpine",
  name: "private-api",
  network: { ingress: false },
});

Live runtime logs

openLogStream keeps one typed Runtime Gateway subscription alive. It waits for the accepted session, maintains heartbeats, renews bounded follows, resumes transient socket generations, and stops without leaving a reconnect loop behind.

const sessionId = crypto.randomUUID();
const issueSession = async () =>
  (
    await cliCloud.api.issueRuntimeSession({
      sessionId,
      requestedScope: "deployment.read",
      subscriptions: ["runtime.logs"],
      userId: "user-id",
      workspaceSlug: "workspace-slug",
    })
  ).runtime;

const logs = cliCloud.runtime.openLogStream(
  await issueSession(),
  {
    requestId: crypto.randomUUID(),
    intentRef: "deployment-intent-id",
    tailLines: 200,
  },
  {
    onLine: ({ line }) => console.log(line),
    onError: (error) => console.error(error.message),
    renewSession: issueSession,
  },
);

await logs.connected;
// Later: logs.stop();