Skip to content

feat: expose cueapi 0.2.0 fire + executions subgroup commands #2

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
govindkavaturi-art merged 1 commit into from
May 6, 2026
Merged

feat: expose cueapi 0.2.0 fire + executions subgroup commands #2

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 29 additions & 3 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -41,6 +41,8 @@ jobs:

## Supported commands

Cue management:

| Command | Purpose |
|----------|----------------------------------------------|
| `create` | Create a new cue (recurring or one-time) |
Expand All @@ -50,9 +52,22 @@ jobs:
| `delete` | Delete a cue |
| `pause` | Pause a cue |
| `resume` | Resume a paused cue |
| `fire` | Fire an existing cue immediately, optional `payload-override` |
| `whoami` | Print authenticated identity |
| `usage` | Show current usage stats |

Worker-execution lifecycle (cueapi 0.2.0+):

| Command | Purpose |
|-------------------------------|------------------------------------------------------------------------|
| `executions-list` | List historical executions, filter by `cue-id` / `status` |
| `executions-list-claimable` | List unclaimed worker executions, filter by `task` / `agent` (server-side) |
| `executions-get` | Fetch one execution by ID |
| `executions-claim` | Atomically claim a specific execution (`worker-id` required) |
| `executions-claim-next` | Claim the next available execution (optional `task` filter) |
| `executions-heartbeat` | Extend the claim lease on an in-flight execution |
| `executions-report-outcome` | Report a write-once outcome (`success: true|false` + optional evidence) |

## Inputs

| Name | Required | Description |
Expand All @@ -67,11 +82,22 @@ jobs:
| `payload` | no | JSON payload string |
| `description` | no | Human-readable cue description |
| `worker` | no | Set `"true"` to use worker transport (no public URL) |
| `cue-id` | no | Target cue ID (get/update/delete/pause/resume) |
| `status` | no | Status filter for `list` (`active` / `paused`) |
| `limit` | no | Max results for `list` |
| `cue-id` | no | Target cue ID (get/update/delete/pause/resume/fire/executions-list) |
| `status` | no | Status filter for `list` (`active`/`paused`) or `executions-list` |
| `limit` | no | Max results for `list` / `executions-list` |
| `offset` | no | Pagination offset for `list` / `executions-list` |
| `api-key` | no | Override API key (prefer `CUEAPI_API_KEY` env from a secret) |
| `cli-version` | no | Pin a specific `cueapi` CLI version (default: latest) |
| `payload-override` | no | JSON payload override for `fire` |
| `merge-strategy` | no | `merge` (default) or `replace` for `fire` |
| `execution-id` | no | Target execution ID (executions-get/claim/heartbeat/report-outcome) |
| `worker-id` | no | Stable worker identifier (executions-claim/claim-next/heartbeat) |
| `task` | no | Task filter for executions-list-claimable / executions-claim-next |
| `agent` | no | Agent filter for executions-list-claimable |
| `success` | no | `true`/`false` for executions-report-outcome |
| `external-id` | no | External system ID for executions-report-outcome |
| `result-url` | no | Public URL evidence for executions-report-outcome |
| `summary` | no | Short human summary for executions-report-outcome (max 500 chars) |

## Outputs

Expand Down
124 changes: 118 additions & 6 deletions action.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,8 +7,17 @@ branding:

inputs:
command:
description: 'CueAPI CLI command to run (create, list, get, update, delete, pause, resume, whoami)'
description: |
CueAPI CLI command to run. Cue management:
create, list, get, update, delete, 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
required: true

# Cue management inputs (existing).
name:
description: 'Cue name (for create/update)'
required: false
Expand Down Expand Up @@ -40,19 +49,56 @@ inputs:
required: false
default: 'false'
cue-id:
description: 'Target cue ID (for get/update/delete/pause/resume)'
description: 'Target cue ID (for get/update/delete/pause/resume/fire/executions-list)'
required: false
status:
description: 'Filter by status for list command (active/paused)'
description: 'Filter by status (active/paused for list; execution status for executions-list)'
required: false
limit:
description: 'Max results for list command'
description: 'Max results for list / executions-list'
required: false
offset:
description: 'Offset for list / executions-list pagination'
required: false
api-key:
description: 'CueAPI API key. Prefer passing via CUEAPI_API_KEY env var from a secret.'
required: false
cli-version:
description: 'Pin a specific cueapi CLI version (e.g. "0.1.0"). Default: latest.'
description: 'Pin a specific cueapi CLI version (e.g. "0.2.0"). Default: latest.'
required: false

# Fire inputs (cueapi 0.2.0+).
payload-override:
description: 'JSON payload override for `fire` (overrides the cue stored payload for this fire only)'
required: false
merge-strategy:
description: 'How payload-override combines with the cue stored payload: merge (default, server-side) or replace'
required: false

# Executions lifecycle inputs (cueapi 0.2.0+).
execution-id:
description: 'Target execution ID (for executions-get/claim/heartbeat/report-outcome)'
required: false
worker-id:
description: 'Stable worker identifier (required for executions-claim, executions-claim-next, executions-heartbeat)'
required: false
task:
description: 'Task filter for executions-list-claimable / executions-claim-next (server-side SQL filter)'
required: false
agent:
description: 'Agent filter for executions-list-claimable (server-side SQL filter)'
required: false
success:
description: 'Outcome success flag for executions-report-outcome: "true" or "false"'
required: false
external-id:
description: 'External system ID for executions-report-outcome (e.g. PR number, doc ID)'
required: false
result-url:
description: 'Public URL for executions-report-outcome evidence (e.g. tweet, PR, doc)'
required: false
summary:
description: 'Short human summary for executions-report-outcome (max 500 chars)'
required: false

outputs:
Expand Down Expand Up @@ -110,6 +156,18 @@ runs:
CUE_ID: ${{ inputs.cue-id }}
STATUS: ${{ inputs.status }}
LIMIT: ${{ inputs.limit }}
OFFSET: ${{ inputs.offset }}
# Fire + executions inputs (cueapi 0.2.0+).
PAYLOAD_OVERRIDE: ${{ inputs.payload-override }}
MERGE_STRATEGY: ${{ inputs.merge-strategy }}
EXECUTION_ID: ${{ inputs.execution-id }}
WORKER_ID: ${{ inputs.worker-id }}
TASK: ${{ inputs.task }}
AGENT: ${{ inputs.agent }}
SUCCESS: ${{ inputs.success }}
EXTERNAL_ID: ${{ inputs.external-id }}
RESULT_URL: ${{ inputs.result-url }}
SUMMARY: ${{ inputs.summary }}
run: |
set -euo pipefail
cmd=(cueapi "$COMMAND")
Expand Down Expand Up @@ -140,11 +198,65 @@ runs:
list)
[ -n "$STATUS" ] && cmd+=(--status "$STATUS")
[ -n "$LIMIT" ] && cmd+=(--limit "$LIMIT")
[ -n "$OFFSET" ] && cmd+=(--offset "$OFFSET")
;;
whoami|usage)
;;
fire)
[ -n "$CUE_ID" ] && cmd+=("$CUE_ID")
[ -n "$PAYLOAD_OVERRIDE" ] && cmd+=(--payload-override "$PAYLOAD_OVERRIDE")
[ -n "$MERGE_STRATEGY" ] && cmd+=(--merge-strategy "$MERGE_STRATEGY")
;;
# Executions subgroup (cueapi 0.2.0+) — these commands map to
# ``cueapi executions <sub>`` (group + subcommand). Override
# the default ``cmd=(cueapi "$COMMAND")`` because COMMAND
# carries a hyphenated name (e.g. "executions-list") and the
# CLI expects the words separated.
executions-list)
cmd=(cueapi executions list)
[ -n "$CUE_ID" ] && cmd+=(--cue-id "$CUE_ID")
[ -n "$STATUS" ] && cmd+=(--status "$STATUS")
[ -n "$LIMIT" ] && cmd+=(--limit "$LIMIT")
[ -n "$OFFSET" ] && cmd+=(--offset "$OFFSET")
;;
executions-list-claimable)
cmd=(cueapi executions list-claimable)
[ -n "$TASK" ] && cmd+=(--task "$TASK")
[ -n "$AGENT" ] && cmd+=(--agent "$AGENT")
;;
executions-get)
cmd=(cueapi executions get)
[ -n "$EXECUTION_ID" ] && cmd+=("$EXECUTION_ID")
;;
executions-claim)
cmd=(cueapi executions claim)
[ -n "$EXECUTION_ID" ] && cmd+=("$EXECUTION_ID")
[ -n "$WORKER_ID" ] && cmd+=(--worker-id "$WORKER_ID")
;;
executions-claim-next)
cmd=(cueapi executions claim-next)
[ -n "$WORKER_ID" ] && cmd+=(--worker-id "$WORKER_ID")
[ -n "$TASK" ] && cmd+=(--task "$TASK")
;;
executions-heartbeat)
cmd=(cueapi executions heartbeat)
[ -n "$EXECUTION_ID" ] && cmd+=("$EXECUTION_ID")
[ -n "$WORKER_ID" ] && cmd+=(--worker-id "$WORKER_ID")
;;
executions-report-outcome)
cmd=(cueapi executions report-outcome)
[ -n "$EXECUTION_ID" ] && cmd+=("$EXECUTION_ID")
if [ "$SUCCESS" = "true" ]; then
cmd+=(--success)
elif [ "$SUCCESS" = "false" ]; then
cmd+=(--failure)
fi
[ -n "$EXTERNAL_ID" ] && cmd+=(--external-id "$EXTERNAL_ID")
[ -n "$RESULT_URL" ] && cmd+=(--result-url "$RESULT_URL")
[ -n "$SUMMARY" ] && cmd+=(--summary "$SUMMARY")
;;
*)
echo "::error::Unsupported command '$COMMAND'. Supported: create, list, get, update, delete, pause, resume, whoami, usage."
echo "::error::Unsupported command '$COMMAND'. Supported: create, list, get, update, delete, pause, resume, whoami, usage, fire, executions-list, executions-list-claimable, executions-get, executions-claim, executions-claim-next, executions-heartbeat, executions-report-outcome."
exit 1
;;
esac
Expand Down