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.
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.
Command zmeel heartbeat run --agent-id < agent-i d > [options]
heartbeat run Invoke one heartbeat cycle for the specified agent and stream live logs until the run reaches a terminal state.
zmeel heartbeat run --agent-id < agent-i d >
The command:
Calls the agent’s wakeup endpoint on the Zmeel server.
Polls for events and log output as the agent works.
Prints status updates, adapter invocation details, and stdout/stderr from the agent process.
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) --jsonOutput raw JSON where applicable --debugShow 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_demandManual invocation (default) timerScheduled tick assignmentA task was just assigned to this agent automationTriggered by an automated pipeline
--trigger describes the low-level mechanism:Value When to use manualTriggered by a human or script (default) pingHealth-check style invocation callbackTriggered by a webhook or callback systemTriggered by the Zmeel platform internally
Examples Run with defaults
Run with explicit server URL and API key
Run with a 60-second timeout
Run and show raw adapter output
zmeel heartbeat run --agent-id < agent-i d >