cueapi/CueAPI
Schedule and verify AI agent jobs from your GitHub Actions workflows using CueAPI.
View on GitHubTrust Signals
- Scorecard Score
- not yet scored
- Maintenance Recency
- Activelast commit May 13, 2026
- License
- None
Pinned Snippet
uses: cueapi/cueapi-action@b11043410bea65163d054f6cccbc9dcdfac30edd # v1.0.0tags can be moved; commit SHAs can't. why a SHA?
Inputs
| name | description | required | default |
|---|---|---|---|
| command | CueAPI CLI command to run. Cue management: create, list, get, update, delete, bulk-delete (max 100 IDs; always passes --yes since CI has no interactive confirm), pause, resume, whoami, usage, fire Worker-execution lifecycle (introduced in cueapi 0.2.0): executions-list, executions-list-claimable, executions-get, executions-claim, executions-claim-next, executions-heartbeat, executions-report-outcome Agent identity (Surface 6 messaging primitive, cueapi-cli 0.3.0+): agents-create, agents-list, agents-get (alias: agents-describe), agents-update, agents-delete, agents-webhook-secret-get, agents-webhook-secret-regenerate (destructive — rotates the secret; always passes --yes since CI has no interactive confirm) Messaging primitive (Surface 6, cueapi-cli 0.3.0+): messages-send, messages-get, messages-read, messages-ack, message-to (top-level ergonomic alias — accepts a recipient by name/slug/agent_id; CLI does roster lookup before sending. Distinct from messages-send which requires a fully-qualified to-agent. Wraps cueapi-cli #40.) Workers (worker registration / cleanup): workers-list, workers-delete Execution verify-class (replay terminal executions + manual verify pipeline, cueapi-cli 0.3.0+): executions-replay, executions-verification-pending, executions-verify | yes | — |
| name | Cue name (for create/update) | no | — |
| cron | Cron expression for recurring cue (for create/update) | no | — |
| at | ISO timestamp for one-time cue (for create) | no | — |
| url | Callback URL (for create/update) | no | — |
| method | HTTP method (default: POST) | no | POST |
| timezone | Timezone (default: UTC) | no | UTC |
| payload | JSON payload string (for create/update) | no | — |
| description | Cue description (for create/update) | no | — |
| worker | Use worker transport (no public URL needed). Set to "true" to enable. | no | false |
| cue-id | Target cue ID (for get/update/delete/pause/resume/fire/executions-list) | no | — |
| cue-ids | Multiple cue IDs for `bulk-delete` (whitespace or newline separated; max 100 per call). Per-ID atomic, NOT batch atomic — IDs that don't exist OR aren't owned by the caller land in the response's `skipped` array (silent skip on miss; no info leak about other tenants' cues). Action always passes --yes (no interactive confirm in CI); CLI sends the X-Confirm-Destructive: true header server-side. | no | — |
| status | Filter by status (active/paused for list; execution status for executions-list) | no | — |
| limit | Max results for list / executions-list | no | — |
| offset | Offset for list / executions-list pagination | no | — |
| api-key | CueAPI API key. Prefer passing via CUEAPI_API_KEY env var from a secret. | no | — |
| cli-version | Pin a specific cueapi CLI version (e.g. "0.2.0"). Default: latest. | no | — |
| payload-override | JSON payload override for `fire` (overrides the cue stored payload for this fire only) | no | — |
| merge-strategy | How payload-override combines with the cue stored payload: merge (default, server-side) or replace | no | — |
| send-at | Optional ISO 8601 timestamp to schedule a future fire (used by `fire` — hosted PR #618) OR a future message send (used by `messages-send` — hosted PR #623, §13). Omitted = run-now/send-now (server default). Past timestamps are forgiving fallback (treated as run/send now). Same semantics across cue-fire and messages-send. | no | — |
| exit-criteria | Required-assertion keys for §14 work-verification-light on `fire` (hosted PR #632). Whitespace-separated list (e.g. "key1 key2 key3"). Receiver MUST report values for every key under outcome.assertions; missing keys mark the execution verification_failed. Pass an empty string to opt out of cue-level required_assertions for this fire. Max 20 keys. | no | — |
| verify | Set "true" to OPT IN to Phase 2 body-verify on `fire` (parity with cueapi-cli #55 + cueapi-python #41, Mike body-verify directive 2026-05-11). When set, cueapi-cli sends X-CueAPI-Verify-Echo header + checks substrate-echoed body matches sent body, failing the Action step (exit 7) on drift. Default OFF for fire because substrate /v1/cues/{id}/fire echoes a pydantic-after-parse body that may include server-side default-population, causing spurious diff vs the CLI's canonical-JSON serialization. Opt in when you know your payload-override serialization matches substrate echo semantics. NOTE: distinct from `no-verify` (which is for messages — default-on opt-out); fire is default-off opt-in. | no | — |
| execution-id | Target execution ID (for executions-get/claim/heartbeat/report-outcome) | no | — |
| worker-id | Stable worker identifier (required for executions-claim, executions-claim-next, executions-heartbeat) | no | — |
| task | Task filter for executions-list-claimable / executions-claim-next (server-side SQL filter) | no | — |
| agent | Agent filter for executions-list-claimable (server-side SQL filter) | no | — |
| outcome-state | Filter `executions-list` by outcome_state (server-side filter). One of: reported_success / reported_failure / verified_success / verification_pending / verification_failed / unknown. | no | — |
| result-type | Filter `executions-list` by evidence result_type (server-side filter). Free-form string matched against the execution's `evidence_result_type` column (e.g. "pr", "issue", "comment", "doc"). | no | — |
| has-evidence | Filter `executions-list` to executions that reported evidence (i.e. `evidence_external_id IS NOT NULL`). Set to "true" to enable; omit/false to apply no filter. The flag is meaningful only when true (server-side `has_evidence=false` is the same as omitting it, just with URL noise). | no | false |
| triggered-by | Filter `executions-list` by triggered_by (server-side filter). One of: scheduled / manual_fire / chain. | no | — |
| success | Outcome success flag — "true" or "false". Used for: - executions-report-outcome (translates to --success / --failure) - executions-verify (translates to --valid / --invalid; omit for server default valid=true) | no | — |
| external-id | External system ID for executions-report-outcome (e.g. PR number, doc ID) | no | — |
| result-url | Public URL for executions-report-outcome evidence (e.g. tweet, PR, doc) | no | — |
| summary | Short human-readable note (max 500 chars). Used for: - executions-report-outcome (--summary) - executions-verify (--reason; most useful with success=false to record why verification failed) | no | — |
| ref | Agent slug or opaque id (for agents-get/update/delete/webhook-secret-get/describe) | no | — |
| slug | Agent slug (for agents-create; URL-safe identifier) | no | — |
| display-name | Agent display name (for agents-create/update) | no | — |
| webhook-url | Agent webhook callback URL (for agents-create/update). Pass empty string + clear-webhook-url=true to remove on update. | no | — |
| clear-webhook-url | Set to "true" on agents-update to remove the agent webhook URL (sentinel for unsetting). Default false. | no | false |
| online-only | Set to "true" on agents-list to filter to currently-online agents only (mutually exclusive with status). Default false. | no | false |
| msg-id | Target message ID (msg_<12 alnum>) for messages-get/read/ack | no | — |
| from-agent | Sender agent — opaque agent_id or slug-form (agent@user). Required for messages-send. | no | — |
| to-agent | Recipient agent. For `messages-send`: opaque agent_id (agt_xxx) or slug-form (agent@user) — must be fully qualified. For `message-to`: also accepts a bare display name or slug; CLI does roster lookup before sending (case-insensitive match against display_name and slug). Required for messages-send and message-to. | no | — |
| body | Message body (1-32768 chars) for messages-send / message-to. Inline; auto-rejected by cueapi-cli when content contains shell metacharacters ($(...), backticks, ${VAR}) — use `message-file` or `body-stdin` instead. Provide exactly one of body / message-file / body-stdin. | no | — |
| message-file | RECOMMENDED for content with shell metacharacters. Path to a file containing the message body. cueapi-cli reads byte-identical (zero shell interpolation). Mint pattern: heredoc with single-quoted EOF marker → file → pass path. Phase 3 of body-verify defense (Mike directive 2026-05-11). | no | — |
| body-stdin | Set "true" to read message body from stdin instead of inline. Use with a preceding step that writes the body to a file + then pipes via `< $FILE` in your workflow. | no | — |
| allow-inline-metachars | Set "true" to override cueapi-cli's Layer 3 force-file guard. Use ONLY when the inline `body` is verified-literal (e.g., shell-tutorial example legitimately containing $(...) text). | no | — |
| no-verify | Set "true" to opt out of Phase 2 body-verify auto-echo (Mike body- verify directive 2026-05-11). Default is verify-on: cueapi-cli sends X-CueAPI-Verify-Echo header + checks substrate-echoed body matches sent body, failing the Action step on drift. Use --no-verify when perf-sensitive flows make the extra response-payload byte-overhead undesirable (rare; one substrate roundtrip already includes the echo). | no | — |
| subject | Optional message subject (max 255 chars) for messages-send | no | — |
| reply-to-message | Previous message ID this reply chains to (msg_<12 alnum>). thread_id inherits. | no | — |
| priority | Message priority 1-5 (server default 3). Receiver-pair limits may downgrade >3 to 3. | no | — |
| expects-reply | Set "true" on messages-send to mark this message as expecting a reply. | no | false |
| reply-to-agent | Decoupled reply target (defaults to the sender). Override when reply should route to a different agent. | no | — |
| metadata | JSON metadata blob for messages-send | no | — |
| idempotency-key | Optional Idempotency-Key (≤256 chars). Different transports per command: - For `messages-send` / `message-to`: sent as the `Idempotency-Key` request header. - For `fire`: sent as the `idempotency_key` body field on cues fire (server FireRequest schema, hosted PR #683). Same key on the same cue within 24h returns the cached execution; same key + DIFFERENT body returns 409 idempotency_key_conflict. Sent as a BODY field, NOT a header — matches the server's FireRequest contract. Same key + same body within 24h returns the existing record HTTP 200 instead of 201. | no | — |
| mode | Delivery mode hint for `messages-send` and `message-to` (Surface 6 v2 delivery_mode; cueapi-cli #41 added it to `message-to`; cueapi-cli #49 added it to `messages send` for parity). One of: live | bg | inbox | webhook | auto (default). live = recipient's attached Live session bg = spawn a fresh background session for the recipient inbox = leave in inbox for pull webhook = POST to the recipient's configured webhook auto = server picks the best supported mode Server may downgrade if the requested mode isn't supported. Defaulting to `auto` matches the CLI's default; the action omits the flag entirely when set to `auto` to keep wire-format identical to pre-Surface-6 senders. | no | — |
| notify | §17 BCC-light (hosted PR #619) — whitespace-separated list of agent refs (max 10). Used by `messages-send` and `message-to`. Each ref gets a stripped notification copy (subject + sender + recipient + 1-line summary, no full body) alongside the main delivery, sharing the main message's thread_id. Each entry must be a fully-qualified agent ref (opaque agt_xxx or slug-form agent@user). Self-bcc is silently de-duped server-side. Notifications skip the monthly quota and are pinned to priority=3. | no | — |
| live-fallback-mode | Agent-id-split refactor (2026-05-12) — controls behavior when the recipient is a Live-sibling agent and its Live session is silent (no fresh heartbeat). Used by `messages-send` and `message-to`. One of: live_only = message queues against the Live agent until that specific Live session attaches fallback_to_background (default) = substrate looks up the BG sibling via parent_agent_id and routes there The action omits the flag entirely when set to `fallback_to_background` (or unset) to keep wire-format identical to pre-refactor senders. Parity with cueapi-cli `messages send --live-fallback-mode` (#56). Design Dock: https://trydock.ai/workspaces/agent-id-split-refactor-2026-05-12 | no | — |
| parent-agent-id | Agent-id-split refactor (2026-05-12) — link this new agent as a sibling of the given parent agent (`agt_xxx` opaque ID). Used by `agents-create` when creating a Live sibling for an existing BG agent: pass the BG agent's id and substrate stores the FK so the router can fall back from Live to BG when the Live session is silent (see `live-fallback-mode`). Omit for standalone (parent) agents. Substrate enforces FK validity. Parity with cueapi-cli `agents create --parent-agent-id` (#56). | no | — |
Outputs
| name | description |
|---|---|
| result | Raw stdout from the cueapi CLI invocation |