Deployments.ai Docs
Command reference

deployments run

Agent execution and timelines

CommandSummary
deployments run listList agent runs in the environment, optionally for one deployment or binding
deployments run searchSearch agent runs
deployments run createCreate an agent run
deployments run getShow a run by ID without its thread
deployments run logsList what the runtime logged while executing a run
deployments run showShow a run within its thread
deployments run messageShow the finalized assistant message for a run
deployments run reserve-message-publicationReserve conversation order before an external automation delivery
deployments run publish-messagePublish a confirmed externally delivered automation message
deployments run release-message-publicationRelease an uncertain external automation delivery reservation
deployments run cancelCancel an agent run
deployments run retryRetry a failed agent run
deployments run replayReplay an agent run
deployments run tailTail 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 (SDK listRuns).
  • Needs an environment: --env or the saved context.
  • Paginated. --page-size sets the page size; pass the returned cursor as --cursor for the next page.
FlagTypeRequiredDefaultDescription
--cursorstring (cursor)Pagination cursor
--page-sizestring (number)Page size
--agent-deployment-idstringAgent deployment ID
--execution-binding-idstringPreview or evaluation execution binding ID
--execution-purposestringExecution purpose: customer, evaluation, or preview
--created-afterstringEarliest creation timestamp
--created-beforestringLatest creation timestamp
--statusstringRun status
--threadstringThread ID
--releasestringAgent release ID

Also accepts the global flags.

Search agent runs.

deployments run search
  • Calls POST /v1/runs/search (SDK searchRuns).
  • Needs an environment: --env or the saved context.
  • Paginated. --page-size sets the page size; pass the returned cursor as --cursor for the next page.
FlagTypeRequiredDefaultDescription
--cursorstring (cursor)Pagination cursor
--page-sizestring (number)Page size
--agent-deployment-idstringAgent deployment ID
--execution-binding-idstringPreview or evaluation execution binding ID
--execution-purposestringExecution purpose: customer, evaluation, or preview
--created-afterstringEarliest creation timestamp
--created-beforestringLatest creation timestamp
--statusstringRun status
--threadstringThread ID
--releasestringAgent release ID

Also accepts the global flags.

deployments run create

Create an agent run.

deployments run create --agent <agent> --message <message>
FlagTypeRequiredDefaultDescription
--agentstringyesAgent deployment ID
--threadstringThread ID
--messagestringyesMessage input
--titlestringThread title
--workspace-idstringWorkspace ID
--rebase-releasebooleanDrop 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>
FlagTypeRequiredDefaultDescription
<id>positionalyesResource 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 (SDK listRunLogs).
  • Needs an environment: --env or the saved context.
  • Paginated. --page-size sets the page size; pass the returned cursor as --cursor for the next page.
FlagTypeRequiredDefaultDescription
--cursorstring (cursor)Pagination cursor
--page-sizestring (number)Page size
<id>positionalyesResource ID
--levelstringMinimum level: debug, info, warn, or error
--sourcestringSource: runtime, model, tool, sandbox, or hosted-code
--tool-callstringTool call ID
--fromstringEarliest line timestamp
--tostringLatest line timestamp, exclusive

Also accepts the global flags.

deployments run show

Show a run within its thread.

deployments run show <id> --thread <thread>
FlagTypeRequiredDefaultDescription
<id>positionalyesResource ID
--threadstringyesThread ID

Also accepts the global flags.

deployments run message

Show the finalized assistant message for a run.

deployments run message <id> --thread <thread>
FlagTypeRequiredDefaultDescription
<id>positionalyesResource ID
--threadstringyesThread 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>
FlagTypeRequiredDefaultDescription
<id>positionalyesResource ID
--threadstringyesThread ID
--messagestringyesDelivered 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>
FlagTypeRequiredDefaultDescription
<id>positionalyesResource ID
--threadstringyesThread ID
--messagestringyesDelivered 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>
FlagTypeRequiredDefaultDescription
<id>positionalyesResource ID
--threadstringyesThread ID
--messagestringyesDelivered message content

Also accepts the global flags.

deployments run cancel

Cancel an agent run.

deployments run cancel <id>
  • Calls POST /v1/runs/{runId}/cancel (SDK cancelRun).
  • Needs an environment: --env or the saved context.
  • Destructive. Live runs ask for confirmation; pass --yes in scripts or with --json.
FlagTypeRequiredDefaultDescription
<id>positionalyesResource ID

Also accepts the global flags.

deployments run retry

Retry a failed agent run.

deployments run retry <id>
  • Calls POST /v1/runs/{runId}/retry (SDK retryRun).
  • Needs an environment: --env or the saved context.
  • Destructive. Live runs ask for confirmation; pass --yes in scripts or with --json.
FlagTypeRequiredDefaultDescription
<id>positionalyesResource ID

Also accepts the global flags.

deployments run replay

Replay an agent run.

deployments run replay <id>
  • Calls POST /v1/runs/{runId}/replay (SDK replayRun).
  • Needs an environment: --env or the saved context.
  • Destructive. Live runs ask for confirmation; pass --yes in scripts or with --json.
  • Sends an idempotency key. The CLI generates one per run; pass --idempotency-key to retry safely.
FlagTypeRequiredDefaultDescription
<id>positionalyesResource 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 (SDK readThreadStream).
  • Needs an environment: --env or the saved context.
  • Streams events as they arrive. With --json, each event prints as a JSON object.
FlagTypeRequiredDefaultDescription
<id>positionalyesRun ID
--threadstringyesThread ID
--followbooleanContinue following events
--cursorstringInitial durable stream cursor
--offsetstringInitial durable stream offset

Also accepts the global flags.

On this page