Skip to main content

Use the TypeScript SDK

In this tutorial, you will use @stacklok/mecatl-sdk to start a private mecated process, create a session, and run one prompt without model-provider credentials.

Prerequisites​

You need:

  • macOS or Linux with Homebrew;
  • Node.js 22 or later;
  • a GitHub personal access token with read:packages; and
  • access to the internal stacklok/mecatl repository and its package.

Install mecated​

Install the released mecated executable from Stacklok's Homebrew tap, then verify that it is available on PATH:

brew install stacklok/tap/mecatl
mecated --version

The version command prints the installed release tag.

Create a project​

Create an empty project directory, then initialize an ESM package:

mkdir mecatl-sdk-quickstart
cd mecatl-sdk-quickstart
npm init -y
npm pkg set type=module

Expose your GitHub token to the package manager:

export GITHUB_PACKAGES_TOKEN=<GITHUB_TOKEN>

Create .npmrc in the project directory. The file refers to the environment variable and does not contain the token value:

.npmrc
@stacklok:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${GITHUB_PACKAGES_TOKEN}

Install the SDK preview and TypeScript:

npm install @stacklok/mecatl-sdk@0.0.1
npm install --save-dev --save-exact typescript@6.0.3

Configure TypeScript​

Create tsconfig.json:

tsconfig.json
{
  "compilerOptions": {
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "outDir": "dist",
    "strict": true,
    "target": "ES2022"
  },
  "include": ["quickstart.ts"]
}

Run a prompt​

Create quickstart.ts:

quickstart.ts
import { spawn } from "@stacklok/mecatl-sdk/node";

const client = await spawn({ args: ["--mock"] });

try {
  const session = await client.sessions.create({});
  const run = await session.run("Say hello from Mecatl");
  const result = await run.result();

  console.log(result.text);
} finally {
  await client.close();
}

Compile and run the program:

npx tsc
node dist/quickstart.js

The offline provider returns:

Mock provider: no real model is configured. Set OPENAI_API_KEY for live use.

Closing the client stops the private daemon and removes its runtime directory. You have created and consumed a complete Mecatl run from TypeScript.

Next steps​

Troubleshooting​

Package installation returns 401 or 404

Confirm that GITHUB_PACKAGES_TOKEN contains a GitHub token with read:packages and that your GitHub account can access the internal stacklok/mecatl repository and package.

The SDK cannot find mecated

Run mecated --version in the same terminal. If the command is unavailable, install Mecatl or pass an absolute binaryPath to spawn().