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

# heartbeat

> Manually trigger a single execution cycle for an agent and stream its live output.

A heartbeat is one execution cycle for an agent — they wake up, check their tools and memory, act on any assigned tasks, and update their state. Normally heartbeats run automatically on a schedule. Use `heartbeat run` to trigger one manually.

<Note>
  You do not need to run heartbeats yourself in a production setup. Zmeel dispatches them automatically based on each agent's schedule and task assignments. Use this command for development, debugging, or to trigger an ad-hoc run without waiting for the next scheduled tick.
</Note>

## Command

```bash theme={null}
zmeel heartbeat run --agent-id <agent-id> [options]
```

***

## heartbeat run

Invoke one heartbeat cycle for the specified agent and stream live logs until the run reaches a terminal state.

```bash theme={null}
zmeel heartbeat run --agent-id <agent-id>
```

The command:

1. Calls the agent's wakeup endpoint on the Zmeel server.
2. Polls for events and log output as the agent works.
3. Prints status updates, adapter invocation details, and stdout/stderr from the agent process.
4. Exits when the run reaches a terminal status: `succeeded`, `failed`, `cancelled`, or `timed_out`.

### Options

| Option                | Description                                                                                     |
| --------------------- | ----------------------------------------------------------------------------------------------- |
| `--agent-id <id>`     | Agent to invoke (required)                                                                      |
| `--api-base <url>`    | Base URL of the Zmeel server API                                                                |
| `--api-key <token>`   | Bearer token for agent-authenticated calls                                                      |
| `--source <source>`   | Invocation source: `timer`, `assignment`, `on_demand`, or `automation` (default: `on_demand`)   |
| `--trigger <trigger>` | Trigger detail: `manual`, `ping`, `callback`, or `system` (default: `manual`)                   |
| `--timeout-ms <ms>`   | Maximum time in milliseconds to wait before giving up (default: `0`, meaning wait indefinitely) |
| `--json`              | Output raw JSON where applicable                                                                |
| `--debug`             | Show raw adapter stdout/stderr JSON chunks instead of formatted output                          |
| `--context <path>`    | Path to a custom context file                                                                   |
| `--profile <name>`    | CLI context profile to use                                                                      |
| `--data-dir <path>`   | Isolate all local state away from `~/.zmeel`                                                    |

### Source and trigger values

`--source` describes what caused the heartbeat in business terms:

| Value        | When to use                            |
| ------------ | -------------------------------------- |
| `on_demand`  | Manual invocation (default)            |
| `timer`      | Scheduled tick                         |
| `assignment` | A task was just assigned to this agent |
| `automation` | Triggered by an automated pipeline     |

`--trigger` describes the low-level mechanism:

| Value      | When to use                                |
| ---------- | ------------------------------------------ |
| `manual`   | Triggered by a human or script (default)   |
| `ping`     | Health-check style invocation              |
| `callback` | Triggered by a webhook or callback         |
| `system`   | Triggered by the Zmeel platform internally |

### Examples

<CodeGroup>
  ```bash Run with defaults theme={null}
  zmeel heartbeat run --agent-id <agent-id>
  ```

  ```bash Run with explicit server URL and API key theme={null}
  zmeel heartbeat run \
    --agent-id <agent-id> \
    --api-base http://localhost:3100 \
    --api-key <token>
  ```

  ```bash Run with a 60-second timeout theme={null}
  zmeel heartbeat run \
    --agent-id <agent-id> \
    --timeout-ms 60000
  ```

  ```bash Run and show raw adapter output theme={null}
  zmeel heartbeat run \
    --agent-id <agent-id> \
    --debug
  ```
</CodeGroup>