deployments run
Agent execution and timelines
| Command | Summary |
|---|---|
deployments run list | List agent runs in the environment, optionally for one deployment or binding |
deployments run search | Search agent runs |
deployments run create | Create an agent run |
deployments run get | Show a run by ID without its thread |
deployments run logs | List what the runtime logged while executing a run |
deployments run show | Show a run within its thread |
deployments run message | Show the finalized assistant message for a run |
deployments run reserve-message-publication | Reserve conversation order before an external automation delivery |
deployments run publish-message | Publish a confirmed externally delivered automation message |
deployments run release-message-publication | Release an uncertain external automation delivery reservation |
deployments run cancel | Cancel an agent run |
deployments run retry | Retry a failed agent run |
deployments run replay | Replay an agent run |
deployments run tail | Tail a run timeline |
deployments run list
List agent runs in the environment, optionally for one deployment or binding.
deployments run list- Calls
GET /v1/runs(SDKlistRuns). - Needs an environment:
--envor the saved context. - Paginated.
--page-sizesets the page size; pass the returned cursor as--cursorfor the next page.
| Flag | Type | Required | Default | Description |
|---|---|---|---|---|
--cursor | string (cursor) | Pagination cursor | ||
--page-size | string (number) | Page size | ||
--agent-deployment-id | string | Agent deployment ID | ||
--execution-binding-id | string | Preview or evaluation execution binding ID | ||
--execution-purpose | string | Execution purpose: customer, evaluation, or preview | ||
--created-after | string | Earliest creation timestamp | ||
--created-before | string | Latest creation timestamp | ||
--status | string | Run status | ||
--thread | string | Thread ID | ||
--release | string | Agent release ID |
Also accepts the global flags.
deployments run search
Search agent runs.
deployments run search- Calls
POST /v1/runs/search(SDKsearchRuns). - Needs an environment:
--envor the saved context. - Paginated.
--page-sizesets the page size; pass the returned cursor as--cursorfor the next page.
| Flag | Type | Required | Default | Description |
|---|---|---|---|---|
--cursor | string (cursor) | Pagination cursor | ||
--page-size | string (number) | Page size | ||
--agent-deployment-id | string | Agent deployment ID | ||
--execution-binding-id | string | Preview or evaluation execution binding ID | ||
--execution-purpose | string | Execution purpose: customer, evaluation, or preview | ||
--created-after | string | Earliest creation timestamp | ||
--created-before | string | Latest creation timestamp | ||
--status | string | Run status | ||
--thread | string | Thread ID | ||
--release | string | Agent release ID |
Also accepts the global flags.
deployments run create
Create an agent run.
deployments run create --agent <agent> --message <message>- Calls
POST /v1/agent-deployments/{agentDeploymentId}/runs(SDKsubmitAgentRun). - Needs an environment:
--envor the saved context. - Sends an idempotency key. The CLI generates one per run; pass
--idempotency-keyto retry safely.
| Flag | Type | Required | Default | Description |
|---|---|---|---|---|
--agent | string | yes | Agent deployment ID | |
--thread | string | Thread ID | ||
--message | string | yes | Message input | |
--title | string | Thread title | ||
--workspace-id | string | Workspace ID | ||
--rebase-release | boolean | Drop the thread's sticky release and re-select |
Also accepts the global flags.
deployments run get
Show a run by ID without its thread.
deployments run get <id>- Calls
GET /v1/runs/{runId}(SDKgetRunById). - Needs an environment:
--envor the saved context.
| Flag | Type | Required | Default | Description |
|---|---|---|---|---|
<id> | positional | yes | Resource ID |
Also accepts the global flags.
deployments run logs
List what the runtime logged while executing a run.
deployments run logs <id>- Calls
GET /v1/runs/{runId}/logs(SDKlistRunLogs). - Needs an environment:
--envor the saved context. - Paginated.
--page-sizesets the page size; pass the returned cursor as--cursorfor the next page.
| Flag | Type | Required | Default | Description |
|---|---|---|---|---|
--cursor | string (cursor) | Pagination cursor | ||
--page-size | string (number) | Page size | ||
<id> | positional | yes | Resource ID | |
--level | string | Minimum level: debug, info, warn, or error | ||
--source | string | Source: runtime, model, tool, sandbox, or hosted-code | ||
--tool-call | string | Tool call ID | ||
--from | string | Earliest line timestamp | ||
--to | string | Latest line timestamp, exclusive |
Also accepts the global flags.
deployments run show
Show a run within its thread.
deployments run show <id> --thread <thread>- Calls
GET /v1/threads/{threadId}/runs/{runId}(SDKgetRun). - Needs an environment:
--envor the saved context.
| Flag | Type | Required | Default | Description |
|---|---|---|---|---|
<id> | positional | yes | Resource ID | |
--thread | string | yes | Thread ID |
Also accepts the global flags.
deployments run message
Show the finalized assistant message for a run.
deployments run message <id> --thread <thread>- Calls
GET /v1/threads/{threadId}/runs/{runId}/message(SDKgetRunMessage). - Needs an environment:
--envor the saved context.
| Flag | Type | Required | Default | Description |
|---|---|---|---|---|
<id> | positional | yes | Resource ID | |
--thread | string | yes | Thread ID |
Also accepts the global flags.
deployments run reserve-message-publication
Reserve conversation order before an external automation delivery.
deployments run reserve-message-publication <id> --thread <thread> --message <message>- Calls
POST /v1/threads/{threadId}/runs/{runId}/message/publication-reservations(SDKreserveRunMessagePublication). - Needs an environment:
--envor the saved context. - Requires
--idempotency-key; reuse the same key when you retry.
| Flag | Type | Required | Default | Description |
|---|---|---|---|---|
<id> | positional | yes | Resource ID | |
--thread | string | yes | Thread ID | |
--message | string | yes | Delivered message content |
Also accepts the global flags.
deployments run publish-message
Publish a confirmed externally delivered automation message.
deployments run publish-message <id> --thread <thread> --message <message>- Calls
POST /v1/threads/{threadId}/runs/{runId}/message/publications(SDKpublishRunMessage). - Needs an environment:
--envor the saved context. - Requires
--idempotency-key; reuse the same key when you retry.
| Flag | Type | Required | Default | Description |
|---|---|---|---|---|
<id> | positional | yes | Resource ID | |
--thread | string | yes | Thread ID | |
--message | string | yes | Delivered message content |
Also accepts the global flags.
deployments run release-message-publication
Release an uncertain external automation delivery reservation.
deployments run release-message-publication <id> --thread <thread> --message <message>- Calls
POST /v1/threads/{threadId}/runs/{runId}/message/publication-releases(SDKreleaseRunMessagePublication). - Needs an environment:
--envor the saved context. - Requires
--idempotency-key; reuse the same key when you retry.
| Flag | Type | Required | Default | Description |
|---|---|---|---|---|
<id> | positional | yes | Resource ID | |
--thread | string | yes | Thread ID | |
--message | string | yes | Delivered message content |
Also accepts the global flags.
deployments run cancel
Cancel an agent run.
deployments run cancel <id>- Calls
POST /v1/runs/{runId}/cancel(SDKcancelRun). - Needs an environment:
--envor the saved context. - Destructive. Live runs ask for confirmation; pass
--yesin scripts or with--json.
| Flag | Type | Required | Default | Description |
|---|---|---|---|---|
<id> | positional | yes | Resource ID |
Also accepts the global flags.
deployments run retry
Retry a failed agent run.
deployments run retry <id>- Calls
POST /v1/runs/{runId}/retry(SDKretryRun). - Needs an environment:
--envor the saved context. - Destructive. Live runs ask for confirmation; pass
--yesin scripts or with--json.
| Flag | Type | Required | Default | Description |
|---|---|---|---|---|
<id> | positional | yes | Resource ID |
Also accepts the global flags.
deployments run replay
Replay an agent run.
deployments run replay <id>- Calls
POST /v1/runs/{runId}/replay(SDKreplayRun). - Needs an environment:
--envor the saved context. - Destructive. Live runs ask for confirmation; pass
--yesin scripts or with--json. - Sends an idempotency key. The CLI generates one per run; pass
--idempotency-keyto retry safely.
| Flag | Type | Required | Default | Description |
|---|---|---|---|---|
<id> | positional | yes | Resource ID |
Also accepts the global flags.
deployments run tail
Tail a run timeline.
deployments run tail <id> --thread <thread>- Calls
GET /v1/threads/{threadId}/stream(SDKreadThreadStream). - Needs an environment:
--envor the saved context. - Streams events as they arrive. With
--json, each event prints as a JSON object.
| Flag | Type | Required | Default | Description |
|---|---|---|---|---|
<id> | positional | yes | Run ID | |
--thread | string | yes | Thread ID | |
--follow | boolean | Continue following events | ||
--cursor | string | Initial durable stream cursor | ||
--offset | string | Initial durable stream offset |
Also accepts the global flags.