Command reference
deployments heartbeat
Agent liveness and heartbeat events
| Command | Summary |
|---|---|
deployments heartbeat create | Create a heartbeat |
deployments heartbeat list | List heartbeats |
deployments heartbeat show | Show a heartbeat |
deployments heartbeat update | Update a heartbeat |
deployments heartbeat archive | Archive a heartbeat |
deployments heartbeat pause | Pause a heartbeat |
deployments heartbeat resume | Resume a heartbeat |
deployments heartbeat fires | List heartbeat fire history |
deployments heartbeat fire | Fire a heartbeat now |
deployments heartbeat create
Create a heartbeat.
deployments heartbeat create --agent-deployment-id <agent-deployment-id> --instructions <instructions>- Calls
POST /v1/heartbeats(SDKcreateHeartbeat). - 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 |
|---|---|---|---|---|
--active-window | string (json) | Heartbeat active window | ||
--agent-deployment-id | string | yes | Agent deployment ID | |
--instructions | string | yes | Heartbeat run instructions | |
--interval-ms | string (number) | Heartbeat interval in milliseconds | ||
--no-skip-when-busy | boolean | Run even while the deployment has an active run | ||
--skip-when-busy | boolean | Skip while the deployment has an active run | ||
--thread-id | string | Conversation thread for heartbeat runs | ||
--timezone | string | IANA timezone | ||
--workspace-id | string | Workspace ID |
Also accepts the global flags.
deployments heartbeat list
List heartbeats.
deployments heartbeat list- Calls
GET /v1/heartbeats(SDKlistHeartbeats). - 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 |
Also accepts the global flags.
deployments heartbeat show
Show a heartbeat.
deployments heartbeat show <id>- Calls
GET /v1/heartbeats/{heartbeatId}(SDKgetHeartbeat). - Needs an environment:
--envor the saved context.
| Flag | Type | Required | Default | Description |
|---|---|---|---|---|
<id> | positional | yes | Resource ID |
Also accepts the global flags.
deployments heartbeat update
Update a heartbeat.
deployments heartbeat update <id>- Calls
PATCH /v1/heartbeats/{heartbeatId}(SDKupdateHeartbeat). - Needs an environment:
--envor the saved context.
| Flag | Type | Required | Default | Description |
|---|---|---|---|---|
<id> | positional | yes | Resource ID | |
--active-window | string (json) | Heartbeat active window | ||
--clear-active-window | boolean | Clear the heartbeat active window | ||
--clear-timezone | boolean | Clear the heartbeat timezone | ||
--instructions | string | Heartbeat run instructions | ||
--interval-ms | string (number) | Heartbeat interval in milliseconds | ||
--no-skip-when-busy | boolean | Run even while the deployment has an active run | ||
--skip-when-busy | boolean | Skip while the deployment has an active run | ||
--timezone | string | IANA timezone |
Also accepts the global flags.
deployments heartbeat archive
Archive a heartbeat.
deployments heartbeat archive <id>- Calls
DELETE /v1/heartbeats/{heartbeatId}(SDKarchiveHeartbeat). - 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 heartbeat pause
Pause a heartbeat.
deployments heartbeat pause <id>- Calls
POST /v1/heartbeats/{heartbeatId}/pause(SDKpauseHeartbeat). - Needs an environment:
--envor the saved context.
| Flag | Type | Required | Default | Description |
|---|---|---|---|---|
<id> | positional | yes | Resource ID |
Also accepts the global flags.
deployments heartbeat resume
Resume a heartbeat.
deployments heartbeat resume <id>- Calls
POST /v1/heartbeats/{heartbeatId}/resume(SDKresumeHeartbeat). - Needs an environment:
--envor the saved context.
| Flag | Type | Required | Default | Description |
|---|---|---|---|---|
<id> | positional | yes | Resource ID |
Also accepts the global flags.
deployments heartbeat fires
List heartbeat fire history.
deployments heartbeat fires <id>- Calls
GET /v1/heartbeats/{heartbeatId}/fires(SDKlistHeartbeatFires). - 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 |
Also accepts the global flags.
deployments heartbeat fire
Fire a heartbeat now.
deployments heartbeat fire <id> --agent-deployment-id <agent-deployment-id>- Calls
POST /v1/heartbeats/{heartbeatId}/fire(SDKfireHeartbeat). - 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 |
|---|---|---|---|---|
<id> | positional | yes | Resource ID | |
--agent-deployment-id | string | yes | Agent deployment ID | |
--fire-key | string | Stable fire key |
Also accepts the global flags.