Routines and Cron Workflows
Palyra distinguishes between Routines (the unified automation engine) and Cron (a compatibility layer for schedule-only tasks). Internally, both are backed by the same routine logic in the daemon, but the CLI provides distinct command groups to cater to different levels of complexity crates/palyra-cli/tests/help_snapshots/cron-help.txt#48-50.Schedule Configuration and Policies
Routines support sophisticated scheduling and execution policies:- Natural Language Schedules: Users can define schedules using phrases like “every weekday at 9” apps/web/src/console/sections/routinesHelpers.ts#97. These are previewed via the
SchedulePreviewcommand crates/palyra-cli/src/args/routines.rs#190-196. - Misfire Policy: Determines behavior when a trigger is missed (e.g., daemon was down). Options include
skip(missed trigger is ignored) orcatch_up(trigger fires once immediately upon recovery) apps/web/src/console/sections/routinesHelpers.ts#68-71. - Concurrency Policy: Governs overlapping executions. Options include
forbid(prevent new run),replace(kill existing run), orqueue_one(buffer one subsequent run) apps/web/src/console/sections/routinesHelpers.ts#62-66. - Quiet Hours: Time windows where routines are suppressed, configurable by timezone apps/web/src/console/sections/routinesHelpers.ts#33-35.
Routine CLI Command Surface
Thepalyra routines command group is the primary interface for full-featured automation crates/palyra-cli/src/args/routines.rs#5-220.
| Command | Description | Key Arguments |
|---|---|---|
upsert | Create or update a routine | --trigger-kind, --prompt, --concurrency, --misfire |
dispatch | Manually trigger a routine with a custom payload | --id, --trigger-payload, --trigger-reason |
logs | View execution history for a specific routine | --id, --limit, --after |
templates | List available routine templates | --json |
export/import | Portable routine definitions | --file, --stdin |
Natural Language to Routine Entity Mapping
The following diagram illustrates how natural language input and CLI arguments are transformed into theRoutineUpsertArgs structure used by the palyra-control-plane.
Title: Natural Language Schedule to Routine Entity Mapping
Sources: crates/palyra-cli/src/commands/routines.rs#108-135, apps/web/src/console/sections/routinesHelpers.ts#97-101
Approvals CLI
The Approvals system provides a Human-in-the-Loop (HITL) gate for sensitive actions, such as tool execution, secret access, or device pairing crates/palyra-cli/src/args/approvals.rs#86-93.Reviewing and Deciding
Thepalyra approvals command group allows operators to audit and resolve pending requests.
- List: Filters approvals by
subject_type(e.g.,Tool,SecretAccess),principal, ordecisionstate crates/palyra-cli/src/args/approvals.rs#5-24. - Decide: Resolves a pending approval.
- Scope: Decisions can be scoped to
Once,Session(valid for the remainder of the current session), orTimeboxed(valid for a specific TTL) crates/palyra-cli/src/args/approvals.rs#77-83. - TTL: A
ttl_mscan be provided for time-limited grants crates/palyra-cli/src/args/approvals.rs#37.
- Scope: Decisions can be scoped to
Approval Export
Theexport command supports auditing by dumping approval records in ndjson or json formats, allowing for ingestion into external SIEM or logging systems crates/palyra-cli/src/args/approvals.rs#43-60.
Sources: crates/palyra-cli/src/args/approvals.rs#4-99
Channels and Router CLI
Channels represent the communication endpoints (e.g., Discord, Slack, Telegram) through which agents interact with users. The CLI provides commands to manage these connectors and audit the routing of messages.Device and Node Management
Because channels often require a running “Node” to bridge external protocols to the Palyra daemon, the CLI includes extensive node and device management:- Node Pairing: Uses
palyra pairing codeto generate PIN or QR codes for new nodes crates/palyra-cli/src/args/pairing.rs#15-24. - Device Lifecycle: Commands like
rotate,revoke, andremovemanage the mTLS identities of connected nodes crates/palyra-cli/src/args/devices.rs#16-41. - Capability Invocation: The
palyra nodes invokecommand allows direct testing of a node’s capabilities (tools) by passing JSON payloads via CLI or stdin crates/palyra-cli/src/args/nodes.rs#41-52.
Data Flow: CLI to Control Plane
The CLI acts as a client to thepalyra-daemon Admin API, facilitated by the palyra-control-plane crate.
Title: CLI Command Execution Data Flow
Sources: crates/palyra-cli/src/commands/routines.rs#193-201, crates/palyra-cli/src/commands/devices.rs#11-13
Implementation Details
- Context Initialization: Most commands start by calling
connect_admin_console, which resolves the daemon’s URL and authentication from the local configuration crates/palyra-cli/src/commands/routines.rs#24-25. - Output Formatting: Commands support a global
--jsonflag. The implementation usesoutput::preferred_json(json)to decide between human-readable text and structured JSON crates/palyra-cli/src/commands/routines.rs#199. - Async Runtime: CLI commands are synchronous entry points that block on an internal Tokio runtime to perform network I/O crates/palyra-cli/src/commands/routines.rs#18-21.