From 4d698783f85ad2f53e56605955715287f97b62cd Mon Sep 17 00:00:00 2001 From: David Susskind Date: Thu, 6 Aug 2026 14:00:43 +0300 Subject: [PATCH] docs(base44-cli): document the workflows list/runs commands MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds reference pages for the new read-only workflows command group (base44/cli#591) and a Workflow Runs section to the command table: - workflows list — workflows with status + run summary - workflows runs — runs across the app; --status/--since/-n filters; failed runs carry the failing task and underlying error Teaches the failed-first debugging flow, the test-run marking (run-now runs are isTestRun), the legacy-app refusal, and that empty results distinguish 'no workflows' from 'no matching runs'. Co-Authored-By: Claude Fable 5 --- skills/base44-cli/SKILL.md | 9 +++ .../base44-cli/references/workflows-list.md | 35 ++++++++++++ .../base44-cli/references/workflows-runs.md | 55 +++++++++++++++++++ 3 files changed, 99 insertions(+) create mode 100644 skills/base44-cli/references/workflows-list.md create mode 100644 skills/base44-cli/references/workflows-runs.md diff --git a/skills/base44-cli/SKILL.md b/skills/base44-cli/SKILL.md index fed6809..f968495 100644 --- a/skills/base44-cli/SKILL.md +++ b/skills/base44-cli/SKILL.md @@ -322,6 +322,15 @@ For complete documentation, see [entities-create.md](references/entities-create. | `base44 functions list` | List all deployed functions on Base44 remote | [functions-list.md](references/functions-list.md) | | `base44 functions pull [name]` | Pull deployed functions from Base44 to local files | [functions-pull.md](references/functions-pull.md) | +### Workflow Runs + +Workflows are the automation system (cron schedules, entity triggers, connector events, in-app agent actions). These commands are read-only: they answer "what workflows exist" and "did my scheduled work fail, and why". + +| Command | Description | Reference | +|---------|-------------|-----------| +| `base44 workflows list` | List this app's workflows with status and run summary | [workflows-list.md](references/workflows-list.md) | +| `base44 workflows runs [--status ] [--since ]` | List workflow runs, newest first; failed runs include the underlying error | [workflows-runs.md](references/workflows-runs.md) | + ### Agent Management Agents are conversational AI assistants that can interact with users, access your app's entities, and call backend functions. Use these commands to manage agent configurations. diff --git a/skills/base44-cli/references/workflows-list.md b/skills/base44-cli/references/workflows-list.md new file mode 100644 index 0000000..6ca1b70 --- /dev/null +++ b/skills/base44-cli/references/workflows-list.md @@ -0,0 +1,35 @@ +# base44 workflows list + +List this app's workflows with their status and run summary. + +## Syntax + +```bash +npx base44 workflows list [options] +``` + +This command can run from a linked project, or outside a project when you pass `--app-id ` or set `BASE44_APP_ID`. + +## Examples + +```bash +# Show all workflows and how their last run went +npx base44 workflows list + +# Machine-readable output +npx base44 workflows list --json +``` + +## Output + +``` +nightly-sync [active] runs: 12, last run failed at 2026-08-05T03:00:00Z (3 consecutive failures) +weekly-digest [paused] runs: 4, last run success at 2026-08-01T09:00:00Z +``` + +With `--json`, each workflow is a record: `id`, `name`, `description`, `status`, `statusReason`, `totalRuns`, `consecutiveFailures`, `lastRunAt`, `lastRunStatus`. + +## Notes + +- `consecutiveFailures > 0` is the signal a workflow needs attention — follow up with `base44 workflows runs --status failed`. +- **Apps that predate Workflows** (legacy automations) are not readable via this command; it fails with an explanation. diff --git a/skills/base44-cli/references/workflows-runs.md b/skills/base44-cli/references/workflows-runs.md new file mode 100644 index 0000000..cf5d134 --- /dev/null +++ b/skills/base44-cli/references/workflows-runs.md @@ -0,0 +1,55 @@ +# base44 workflows runs + +List workflow runs for this app, newest first. This is the fastest way to answer "did my scheduled work fail, and why" — each failed run carries the task that failed and the underlying error. + +## Syntax + +```bash +npx base44 workflows runs [options] +``` + +This command can run from a linked project, or outside a project when you pass `--app-id ` or set `BASE44_APP_ID`. + +## Options + +| Option | Description | Required | +|--------|-------------|----------| +| `--status ` | Filter by run status: `running`, `completed`, `failed`, `cancelled` | No | +| `--since ` | Show runs started after this time. ISO datetime or relative shorthand (e.g. `1h`, `30m`, `2d`) | No | +| `-n, --limit ` | Number of runs to return (1-200, default: 30) | No | + +## Examples + +```bash +# Latest runs across all workflows +npx base44 workflows runs + +# Did anything fail? (start here when debugging) +npx base44 workflows runs --status failed + +# Failures in the last day +npx base44 workflows runs --status failed --since 1d + +# Machine-readable output +npx base44 workflows runs --status failed --json +``` + +## Output + +Each run shows its start time, status, workflow name, trigger type, and duration. Failed and cancelled runs also show the error: + +``` +2026-08-05 04:00:46 FAILED nightly-sync (scheduled) 56.8s + Task 'call_fn' failed: Backend function 'sync-orders' returned HTTP 500: {...} +``` + +With `--json`, each run is a record: `runId`, `workflowId`, `workflowName`, `triggerType`, `status`, `startedAt`, `completedAt`, `durationMs`, `stepsCount`, `errorMessage`, `isTestRun`, `statusReason`. + +## Notes + +- **Trigger types**: `scheduled` (cron), `entity`, `connector`, `in_app_agent`, and `manual`. +- **Test runs are included.** Runs fired via "run now" (including the dashboard's test button) are marked `(test)` in the output and `isTestRun: true` in JSON. If you just created a workflow and fired it to verify, your run WILL appear — marked as a test run. +- A failed run's `errorMessage` names the failing task and, when a backend function was the cause, includes the function's HTTP failure. To dig further into that function's own logs, use `base44 logs --function ` — and remember function logs can take ~30s to appear. +- `statusReason` is a typed reason populated only for failed/cancelled runs (e.g. `insufficient_credits`); read it together with `status`. +- **Apps that predate Workflows** (legacy automations) are not readable via this command; it fails with an explanation rather than returning an empty list. +- An empty result tells you whether the app has no workflows at all, or has workflows but no matching runs — read the message, don't assume.