---
title: "Run a single command · Ataris docs"
description: "Trace a one-shot agent run in a script or CI job, then read its result from the SDK."
canonical: "https://ataris.dev/docs/guides/run-a-command"
last-updated: 2026-10-12
---
# Run a single command

Trace a one-shot agent run in a script or CI job, then read its result from the SDK.

For a one-shot agent run in a script or a CI job, run the agent through the `ataris` CLI, then read the session back with the SDK or the REST API: its final state, its flagged events, and a link to its timeline.

## Run the agent

Tag the run so you can find it again:

```bash
ataris --agent test-fixer --tag run:$GITHUB_RUN_ID claude -p "Fix the failing test"
```

The CLI exits with the agent's exit code once the session is finished.

## Read the result

```ts
import { Ataris } from "@ataris/sdk"

const ataris = new Ataris({ apiKey: process.env.ATARIS_API_KEY })

const { sessions } = await ataris.sessions.list({ tag: [`run:${process.env.GITHUB_RUN_ID}`], limit: 1 })
const [run] = sessions
console.log(run.state, run.flaggedCount, run.dashboardPath)
```

`state` is `succeeded`, `failed`, or `stopped`. `flaggedCount` is how many events were flagged, such as credential reads or outbound traffic.

## Or follow it live

From another process, follow the session while the agent works:

```ts
const session = await ataris.sessions.get(sessionId)

for await (const event of session.events()) {
  console.log(event.lane, event.kind, event.summary, event.verdict ?? "")
}
console.log(session.data.state)
```

The loop finishes when the session ends. See [Stream trace events](/docs/guides/stream-events).

## Without the SDK

The same lookup over the [REST API](/docs/reference/api):

```bash
curl "https://api.ataris.dev/v1/sessions?tag=run:$GITHUB_RUN_ID&limit=1" \
  -H "Authorization: Bearer $ATARIS_API_KEY"
```