apus system
System-level helpers for the Gateway: enqueue system events, control heartbeats, and view presence.
All system subcommands use Gateway RPC and accept the shared client flags:
| Flag | Default | Description |
|---|---|---|
--url <url> |
gateway.remote.url when configured |
Gateway WebSocket URL. |
--port <port> |
none | Local Gateway port. |
--token <token> |
none | Gateway token (if required). |
--password <password> |
none | Gateway password (if required). |
--timeout <ms> |
30000 |
RPC timeout in milliseconds. |
--expect-final |
off | Wait for final response (agent). |
--json |
off | Output JSON. heartbeat last/enable/disable and system presence always print the raw RPC JSON payload regardless of this flag; system event uses it to switch between JSON and a plain ok line. |
Common commands
apus system event --text "Check for urgent follow-ups" --mode now
apus system event --text "Check for urgent follow-ups" --url ws://127.0.0.1:18789 --token "$APUS_GATEWAY_TOKEN"
apus system heartbeat enable
apus system heartbeat last
apus system presence
system event
Enqueue a system event on the main session by default. The next
heartbeat injects it as a System: line in the prompt. Use --mode now to
trigger the heartbeat immediately; next-heartbeat (default) waits for the
next scheduled tick.
Pass --session-key to target a specific session, for example to relay an
async-task completion back to the channel that started it.
With heartbeat.isolatedSession: true, a targeted wake reads and consumes the
event from the selected session while running in a fresh heartbeat session.
Events queued for other sessions stay untouched.
Timing exception with --session-key: when --session-key is supplied,
--mode next-heartbeat collapses to an immediate targeted wake instead of
waiting for the next scheduled tick. Targeted wakes use heartbeat intent
immediate so they bypass the runner's not-due gate that would otherwise
defer (and effectively drop) an event-intent wake. If you want delayed
delivery, omit --session-key so the event lands on the main session and
rides the next regular heartbeat.
Flags:
--text <text>: required system event text.--mode <mode>:nowornext-heartbeat(default).--session-key <sessionKey>: optional; target a specific agent session instead of the agent's main session. Keys that do not belong to the resolved agent fall back to the agent's main session.
system heartbeat last|enable|disable
last: show the last heartbeat event.enable: turn heartbeats back on (use this if they were disabled).disable: pause heartbeats.
system presence
List the current system presence entries the Gateway knows about (nodes, instances, and similar status lines).
Notes
- Requires a running Gateway reachable by your current config (local or remote).
- System events are ephemeral and not persisted across restarts.