> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wednesdayai.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# agent nudge

# `wednesdayai agent nudge`

`wednesdayai agent nudge` (alias `openclaw agent nudge`) hands a payload to an agent's **main
persona** and wakes it to decide what to do. It enqueues an `agent.turn` with `kind=nudge`.
It does not publish a heartbeat signal or call `runHeartbeatOnce`. It is the script-callable
surface of the [nudge contract](https://docs.wednesdayai.dev/next/admin/gateway/heartbeat.md#nudge-wake-the-main-persona): a cheap check
lives in your script; the expensive persona turn runs only when you call this command.

The persona behaves **silent-unless-it-decides** — it receives the payload as non-user context and
sends a user-facing message only when warranted, otherwise acknowledges with no delivery (the
existing heartbeat relay semantics). A nudge carries the `delay` busy policy: while a main turn is
in flight the nudge is accepted only after it is persisted in `bus_work_items`, then delivers once
that turn completes, instead of being dropped. Parked nudges are bounded per session (cap 32); a
nudge that overflows the cap is rejected. On Gateway restart, recovery re-arms only those
producer-accepted pending nudges; it does not execute at boot.

Related:

* Coordination model, grants, and dedupe: [Agent coordination](https://docs.wednesdayai.dev/next/developers/concepts/agent-coordination)
* Nudge contract + wake-gate: [Heartbeat](https://docs.wednesdayai.dev/next/admin/gateway/heartbeat.md#nudge-wake-the-main-persona)
* Plugin-SDK nudge: [Agent Signals](https://docs.wednesdayai.dev/next/developers/plugins/agent-signals#nudge)
* Heartbeat vs cron guidance: [Cron vs Heartbeat](https://docs.wednesdayai.dev/next/users/automation/cron-vs-heartbeat.md)

## Usage

```text theme={"dark"}
wednesdayai agent nudge [text] [flags]
```

## Flags

* `--text <text>`: nudge text (required; also accepted as a positional argument).
* `--data <json>`: structured payload as a JSON object (parsed; invalid JSON or a non-object errors).
* `--agent <id>`: target agent id (defaults to the default agent's main session).
* `--session <key>`: a session **within** the agent chosen by `--agent` (operator-only). It does
  not select the agent: the key must belong to `--agent` (or to the default agent when `--agent`
  is omitted), otherwise the nudge is refused with `session-agent-mismatch`. Pass both, e.g.
  `--agent ops --session agent:ops:main`.
* `--dedupe-key <key>`: idempotency key — the same key never wakes the agent twice. Dedupe is
  scoped to (requester, target session, key) and holds for the life of the durable row, not a
  time window. See [Agent coordination](https://docs.wednesdayai.dev/next/developers/concepts/agent-coordination#dedupe).
* `--reason <reason>`: accepted for compatibility and ignored.
* `--json`: print the raw result (`{ ok, sessionKey, signalId }`) as JSON.

Exit code is `0` when the nudge is durably admitted. The command goes through the authorized
coordination seam (`requestAuthorizedNudge`), and the response confirms durable admission. Human
output is:

```text theme={"dark"}
Nudge accepted for session agent:main:main (work agent-turn:nudge:operator:dedupe:99a9adce02b7215ea34ab00eb9e162c4).
```

`signalId` is the idempotency key of the persisted `agent.turn` row: repeating the same command
with the same `--dedupe-key` returns the same work id and does not admit a second row. A refusal
is now reported back instead of being silently dropped: nudging an agent id that is not
configured fails with `unknown-agent`, and the other reason-bearing outcomes (`self-target`,
`session-agent-mismatch` — a `--session` key naming a different agent than `--agent` —
`depth-exceeded`) surface as `INVALID_REQUEST` gateway errors. Two outcomes surface as
`UNAVAILABLE`: an enqueue failure, and `rejected-overflow` (the target session already holds
its cap of 32 parked delayed turns), which is marked `retryable` because it clears once the
lane drains. Non-zero means the CLI rejected the input (empty text or
invalid `--data`), the seam refused the nudge, or the gateway call failed. Only the legacy
internal path (cron and heartbeat producers calling `requestNudge`) remains fire-and-forget, so
its busy, overflow, and enqueue outcomes are still not reported back.

The Gateway method behind this command (`agent.nudge`) validates the same contract for CLI,
Web UI, and automation clients:

* `text` is required and must be non-empty.
* `data`, when present, must be a JSON object.
* `agentId`, `sessionKey`, `source`, and `dedupeKey` must be non-empty strings when present.
* `ttlMs`, when present, must be an integer greater than or equal to 1.
* `priority`, when present, must be one of `low`, `normal`, `high`, or `urgent`.
* `reason`, `source`, `ttlMs`, `priority`, and `requiresIdle` are accepted and ignored.
* Unknown fields are rejected instead of being ignored.

## Examples

Nudge the default agent with plain text:

```bash theme={"dark"}
wednesdayai agent nudge "New deploy finished — anything to follow up?"
```

Nudge a specific agent with a structured payload and a reason:

```bash theme={"dark"}
wednesdayai agent nudge \
  --agent ops \
  --text "3 new high-priority tickets" \
  --data '{"count":3,"queue":"sev1"}' \
  --reason inbox
```

Wire an external watcher (the cheap check is your script; the nudge is conditional):

```bash theme={"dark"}
count=$(curl -sf https://example.test/api/unread | jq '.count')
if [ "$count" -gt 0 ]; then
  wednesdayai agent nudge --agent ops --text "$count unread items" --data "{\"count\":$count}"
fi
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.