CLI

The Better Agent CLI generates a .d.ts file from your app's agent definitions. This gives your client full type safety, with typed agent names, context schemas, and tool contracts, without importing server code.

Generate Client Types

Terminal

npx @better-agent/cli generate type --config ./server.ts

Or with the global command:

Terminal

better-agent generate type --config ./server.ts

This discovers exported betterAgent() instances in the config file, extracts agent and tool type information, and writes a portable type declaration.

Options

Option	Default	Description
`--config <path...>`	—	One or more config file paths. Required.
`--cwd <path>`	`process.cwd()`	Base directory for resolving relative paths.
`--out <path>`	`better-agent.types.d.ts`	Output path for the generated `.d.ts` file.
`--name <identifier>`	`BAClientApp`	Exported type alias name.
`--yes`	`false`	Skip prompts and overwrite the output file.

Example

Terminal

npx @better-agent/cli generate type \
  --config ./server.ts \
  --out ./src/types/better-agent.d.ts \
  --name MyApp \
  --yes

Use the Generated Types

Import the generated type and pass it to createClient for full type inference.

client.ts

import type { BAClientApp } from "./better-agent.types";
import { createClient } from "@better-agent/client";

const client = createClient<BAClientApp>({
  baseURL: "http://localhost:3000/api",
});

const result = await client.run("assistant", {
  input: "Hello!",
});

Polyrepo Setup

When your client and server live in separate repositories, generate the types in the server repo and copy or publish the output.

Generate in the server:

Terminal

npx @better-agent/cli generate type \
  --config ./better-agent.ts \
  --out ../client/src/types/server.d.ts

Import in the client:

client.ts

import type { BAClientApp } from "./types/server";
import { createClient } from "@better-agent/client";

const client = createClient<BAClientApp>({
  baseURL: "https://api.example.com",
});

Config Discovery

The CLI loads TypeScript or JavaScript files using the runtime bundler and searches for exported betterAgent() app instances.

If a file exports multiple apps, the CLI lists them and prompts you to choose. Use --yes to select all without prompting.

Troubleshooting

Config doesn't load

The CLI resolves imports relative to the config file. If your project uses path aliases such as @/, they may not resolve in the CLI's loader. Use relative imports in your config file.

server.ts

import { tools } from "./tools";
import { tools } from "@/tools";

No app export found

The config file must export a betterAgent() return value. Make sure it's a named or default export, not an unexported variable.

server.ts

export const app = betterAgent({ agents: [myAgent] });
const app = betterAgent({ agents: [myAgent] });

On this page