Run scripts - Botpress

adk run executes a TypeScript script with the ADK runtime fully initialized. Your script can use all of your agent’s primitives, integrations, and runtime utilities like client, actions, bot, and user.

Basic usage

adk run scripts/seed-data.ts
adk run scripts/migrate.ts --prod
adk run scripts/report.ts arg1 arg2

Writing a script

Your script exports a function that the runner calls:

// scripts/seed-data.ts
import { actions } from "@botpress/runtime"
import OrderTable from "../src/tables/order-table"

export default async function () {
  await OrderTable.createRows({
    rows: [
      { userId: "user-1", total: 99.99, status: "pending" },
      { userId: "user-2", total: 149.99, status: "completed" },
    ],
  })

  console.log("Seed data created")
}

The runner looks for exports in this order:

export default function
export function run
export function main
Top-level code (runs on import)

Arguments

Extra arguments after the script path are passed to your function. Positional arguments pass through directly; put flag-like arguments (anything starting with -) after a -- separator so Commander doesn’t try to parse them:

adk run scripts/process.ts order-123
adk run scripts/process.ts -- --limit 100 --verbose

export default async function (...args: string[]) {
  console.log(args)  // ["order-123"] or ["--limit", "100", "--verbose"]
}

Production mode

By default, scripts run against your dev bot. Use --prod to run against the production bot:

adk run scripts/migrate.ts --prod

Use cases

Seed data into tables for development or testing
Run migrations to update table schemas or transform data
Generate reports by querying tables and knowledge bases
Maintenance tasks like cleaning up old data or re-indexing
Test actions by calling them directly outside a conversation

Last modified on April 27, 2026

Debug with logs and traces

Introduction to Zai

​Basic usage

​Writing a script

​Arguments

​Production mode

​Use cases

Basic usage

Writing a script

Arguments

Production mode

Use cases