feat: add system cli
parent
dfa80e1e5d
commit
71203829d8
@ -0,0 +1,55 @@
|
||||
---
|
||||
summary: "CLI reference for `clawdbot system` (system events, heartbeat, presence)"
|
||||
read_when:
|
||||
- You want to enqueue a system event without creating a cron job
|
||||
- You need to enable or disable heartbeats
|
||||
- You want to inspect system presence entries
|
||||
---
|
||||
|
||||
# `clawdbot system`
|
||||
|
||||
System-level helpers for the Gateway: enqueue system events, control heartbeats,
|
||||
and view presence.
|
||||
|
||||
## Common commands
|
||||
|
||||
```bash
|
||||
clawdbot system event --text "Check for urgent follow-ups" --mode now
|
||||
clawdbot system heartbeat enable
|
||||
clawdbot system heartbeat last
|
||||
clawdbot system presence
|
||||
```
|
||||
|
||||
## `system event`
|
||||
|
||||
Enqueue a system event on the **main** session. The next heartbeat will inject
|
||||
it as a `System:` line in the prompt. Use `--mode now` to trigger the heartbeat
|
||||
immediately; `next-heartbeat` waits for the next scheduled tick.
|
||||
|
||||
Flags:
|
||||
- `--text <text>`: required system event text.
|
||||
- `--mode <mode>`: `now` or `next-heartbeat` (default).
|
||||
- `--json`: machine-readable output.
|
||||
|
||||
## `system heartbeat last|enable|disable`
|
||||
|
||||
Heartbeat controls:
|
||||
- `last`: show the last heartbeat event.
|
||||
- `enable`: turn heartbeats back on (use this if they were disabled).
|
||||
- `disable`: pause heartbeats.
|
||||
|
||||
Flags:
|
||||
- `--json`: machine-readable output.
|
||||
|
||||
## `system presence`
|
||||
|
||||
List the current system presence entries the Gateway knows about (nodes,
|
||||
instances, and similar status lines).
|
||||
|
||||
Flags:
|
||||
- `--json`: machine-readable output.
|
||||
|
||||
## Notes
|
||||
|
||||
- Requires a running Gateway reachable by your current config (local or remote).
|
||||
- System events are ephemeral and not persisted across restarts.
|
||||
@ -1,37 +0,0 @@
|
||||
import type { Command } from "commander";
|
||||
import { danger } from "../../globals.js";
|
||||
import { defaultRuntime } from "../../runtime.js";
|
||||
import { formatDocsLink } from "../../terminal/links.js";
|
||||
import { theme } from "../../terminal/theme.js";
|
||||
import type { GatewayRpcOpts } from "../gateway-rpc.js";
|
||||
import { addGatewayClientOptions, callGatewayFromCli } from "../gateway-rpc.js";
|
||||
|
||||
export function registerWakeCommand(program: Command) {
|
||||
addGatewayClientOptions(
|
||||
program
|
||||
.command("wake")
|
||||
.description("Enqueue a system event and optionally trigger an immediate heartbeat")
|
||||
.requiredOption("--text <text>", "System event text")
|
||||
.option("--mode <mode>", "Wake mode (now|next-heartbeat)", "next-heartbeat")
|
||||
.option("--json", "Output JSON", false),
|
||||
)
|
||||
.addHelpText(
|
||||
"after",
|
||||
() => `\n${theme.muted("Docs:")} ${formatDocsLink("/cli/wake", "docs.clawd.bot/cli/wake")}\n`,
|
||||
)
|
||||
.action(async (opts: GatewayRpcOpts & { text?: string; mode?: string }) => {
|
||||
try {
|
||||
const result = await callGatewayFromCli(
|
||||
"wake",
|
||||
opts,
|
||||
{ mode: opts.mode, text: opts.text },
|
||||
{ expectFinal: false },
|
||||
);
|
||||
if (opts.json) defaultRuntime.log(JSON.stringify(result, null, 2));
|
||||
else defaultRuntime.log("ok");
|
||||
} catch (err) {
|
||||
defaultRuntime.error(danger(String(err)));
|
||||
defaultRuntime.exit(1);
|
||||
}
|
||||
});
|
||||
}
|
||||
@ -0,0 +1,125 @@
|
||||
import type { Command } from "commander";
|
||||
|
||||
import { danger } from "../globals.js";
|
||||
import { defaultRuntime } from "../runtime.js";
|
||||
import { formatDocsLink } from "../terminal/links.js";
|
||||
import { theme } from "../terminal/theme.js";
|
||||
import type { GatewayRpcOpts } from "./gateway-rpc.js";
|
||||
import { addGatewayClientOptions, callGatewayFromCli } from "./gateway-rpc.js";
|
||||
|
||||
type SystemEventOpts = GatewayRpcOpts & { text?: string; mode?: string; json?: boolean };
|
||||
|
||||
const normalizeWakeMode = (raw: unknown) => {
|
||||
const mode = typeof raw === "string" ? raw.trim() : "";
|
||||
if (!mode) return "next-heartbeat" as const;
|
||||
if (mode === "now" || mode === "next-heartbeat") return mode;
|
||||
throw new Error("--mode must be now or next-heartbeat");
|
||||
};
|
||||
|
||||
export function registerSystemCli(program: Command) {
|
||||
const system = program
|
||||
.command("system")
|
||||
.description("System tools (events, heartbeat, presence)")
|
||||
.addHelpText(
|
||||
"after",
|
||||
() =>
|
||||
`\n${theme.muted("Docs:")} ${formatDocsLink("/cli/system", "docs.clawd.bot/cli/system")}\n`,
|
||||
);
|
||||
|
||||
addGatewayClientOptions(
|
||||
system
|
||||
.command("event")
|
||||
.description("Enqueue a system event and optionally trigger a heartbeat")
|
||||
.requiredOption("--text <text>", "System event text")
|
||||
.option("--mode <mode>", "Wake mode (now|next-heartbeat)", "next-heartbeat")
|
||||
.option("--json", "Output JSON", false),
|
||||
).action(async (opts: SystemEventOpts) => {
|
||||
try {
|
||||
const text = typeof opts.text === "string" ? opts.text.trim() : "";
|
||||
if (!text) throw new Error("--text is required");
|
||||
const mode = normalizeWakeMode(opts.mode);
|
||||
const result = await callGatewayFromCli("wake", opts, { mode, text }, { expectFinal: false });
|
||||
if (opts.json) defaultRuntime.log(JSON.stringify(result, null, 2));
|
||||
else defaultRuntime.log("ok");
|
||||
} catch (err) {
|
||||
defaultRuntime.error(danger(String(err)));
|
||||
defaultRuntime.exit(1);
|
||||
}
|
||||
});
|
||||
|
||||
const heartbeat = system.command("heartbeat").description("Heartbeat controls");
|
||||
|
||||
addGatewayClientOptions(
|
||||
heartbeat
|
||||
.command("last")
|
||||
.description("Show the last heartbeat event")
|
||||
.option("--json", "Output JSON", false),
|
||||
).action(async (opts: GatewayRpcOpts & { json?: boolean }) => {
|
||||
try {
|
||||
const result = await callGatewayFromCli("last-heartbeat", opts, undefined, {
|
||||
expectFinal: false,
|
||||
});
|
||||
defaultRuntime.log(JSON.stringify(result, null, 2));
|
||||
} catch (err) {
|
||||
defaultRuntime.error(danger(String(err)));
|
||||
defaultRuntime.exit(1);
|
||||
}
|
||||
});
|
||||
|
||||
addGatewayClientOptions(
|
||||
heartbeat
|
||||
.command("enable")
|
||||
.description("Enable heartbeats")
|
||||
.option("--json", "Output JSON", false),
|
||||
).action(async (opts: GatewayRpcOpts & { json?: boolean }) => {
|
||||
try {
|
||||
const result = await callGatewayFromCli(
|
||||
"set-heartbeats",
|
||||
opts,
|
||||
{ enabled: true },
|
||||
{ expectFinal: false },
|
||||
);
|
||||
defaultRuntime.log(JSON.stringify(result, null, 2));
|
||||
} catch (err) {
|
||||
defaultRuntime.error(danger(String(err)));
|
||||
defaultRuntime.exit(1);
|
||||
}
|
||||
});
|
||||
|
||||
addGatewayClientOptions(
|
||||
heartbeat
|
||||
.command("disable")
|
||||
.description("Disable heartbeats")
|
||||
.option("--json", "Output JSON", false),
|
||||
).action(async (opts: GatewayRpcOpts & { json?: boolean }) => {
|
||||
try {
|
||||
const result = await callGatewayFromCli(
|
||||
"set-heartbeats",
|
||||
opts,
|
||||
{ enabled: false },
|
||||
{ expectFinal: false },
|
||||
);
|
||||
defaultRuntime.log(JSON.stringify(result, null, 2));
|
||||
} catch (err) {
|
||||
defaultRuntime.error(danger(String(err)));
|
||||
defaultRuntime.exit(1);
|
||||
}
|
||||
});
|
||||
|
||||
addGatewayClientOptions(
|
||||
system
|
||||
.command("presence")
|
||||
.description("List system presence entries")
|
||||
.option("--json", "Output JSON", false),
|
||||
).action(async (opts: GatewayRpcOpts & { json?: boolean }) => {
|
||||
try {
|
||||
const result = await callGatewayFromCli("system-presence", opts, undefined, {
|
||||
expectFinal: false,
|
||||
});
|
||||
defaultRuntime.log(JSON.stringify(result, null, 2));
|
||||
} catch (err) {
|
||||
defaultRuntime.error(danger(String(err)));
|
||||
defaultRuntime.exit(1);
|
||||
}
|
||||
});
|
||||
}
|
||||
Loading…
Reference in New Issue