Async Runs

Monitor and manage asynchronous agent processing jobs.

runs

List async job runs across agents.

lettactl get runs [agent] [options]

Options

Flag	Type	Description
--active	boolean	Show only active/running jobs
--agent, -a	string	Filter by agent name (alias for positional)
--limit, -l	number	Limit number of results
--watch, -w	boolean	Continuously poll and refresh the run list (Ctrl+C to stop)

Examples

lettactl get runs

lettactl get runs my-agent

lettactl get runs --active

lettactl get runs my-agent --watch

run

Get details about a specific async run.

lettactl run <run-id> [options]

Options

Flag	Type	Description
--wait	boolean	Wait for the run to complete
--stream	boolean	Stream run output
--messages	boolean	Show messages produced by the run

Examples

lettactl run abc-123

lettactl run abc-123 --wait --messages

track

Track async runs until completion. Auto-exits when all runs reach a terminal state. Exit code 1 if any run failed (CI/CD friendly).

lettactl track [run-ids...] [options]

Options

Flag	Type	Description
--agent, -a	string	Track all active runs for an agent

Examples

lettactl track <run-id-1> <run-id-2>

lettactl track --agent my-agent

run-delete

Cancel and delete a specific async run.

lettactl run-delete <run-id>

Examples

lettactl run-delete abc-123

SDK: Run Management

The LettaCtl SDK exposes run management methods for programmatic use: sendMessage, getRun, waitForRun, listRuns, and deleteRun.

import { LettaCtl } from 'lettactl'

Examples

const ctl = new LettaCtl({ lettaBaseUrl: 'http://localhost:8283' });
const run = await ctl.sendMessage(agentId, 'Hello');
const completed = await ctl.waitForRun(run.id, { timeout: 60 });

const runs = await ctl.listRuns(agentId);
const activeRuns = await ctl.listRuns(agentId, { active: true });
const limited = await ctl.listRuns(agentId, { limit: 5 });

await ctl.deleteRun(runId);

import { isRunTerminal, getEffectiveRunStatus } from 'lettactl';
const run = await ctl.getRun(runId);
if (isRunTerminal(run)) {
  console.log('Done:', getEffectiveRunStatus(run));
}