Skip to main content
This guide covers one breaking change in @outputai/cli: output workflow debug now reads the run from Temporal instead of the API’s trace log, and its output is completely different. Nothing in your workflow code changes. If you only run the command by hand, you only need to point it at your Temporal. If a script, a CI job or an agent skill parses its output, update the parser.

What changed

v0.17.0 and earlier asked the API for the trace of a run (GET /workflow/:id/trace-log) and printed it as a text tree, or as the trace JSON with --json. That path needed the API to be reachable and, in production, to hold the AWS credentials for the trace bucket. It failed with Missing AWS keys to authenticate when both trace destinations were on and the API had no keys. v0.18.0 reads the run’s history from Temporal. No API, no trace files, no S3, and the same behavior in development and production.
  • Standard output is one JSON document with an entry for every workflow: the run, then each child workflow. Every entry holds that workflow’s Temporal history events, oldest first.
  • Child workflows are always included, as their own entries.
  • --json is accepted and ignored. The output is always JSON, and it is never the trace JSON.
  • Long payload values are always truncated. Before, --json printed the full trace.
  • New flags: --run-id, --profile, --address and --namespace.
  • Errors go to stderr with a non-zero exit code and nothing on stdout.
  • The Fetching debug information... and Trace source: ... lines are gone.
  • The 256 MB trace limit from v0.17.0 no longer applies to this command.

Connect to Temporal

The CLI used to need only the API. workflow debug now connects to Temporal from the machine that runs it, so that machine must reach your Temporal. Locally nothing changes: output dev publishes Temporal on localhost:7233, and the command uses it by default. If you override OUTPUT_TEMPORAL_HOST_PORT, the default follows it. For a remote Temporal, use a profile in temporal.toml, the file the temporal CLI uses. It lives in temporalio/ under your user config directory (~/Library/Application Support on macOS, $XDG_CONFIG_HOME or ~/.config on Linux, %APPDATA% on Windows).
You can also use environment variables (TEMPORAL_ADDRESS, TEMPORAL_NAMESPACE, TEMPORAL_API_KEY, TEMPORAL_PROFILE) or the --address and --namespace flags. Highest priority first: flags, environment variables, the profile, then the defaults. The API key and TLS material have no flag, so they never end up in shell history. OUTPUT_API_URL and OUTPUT_API_AUTH_TOKEN are not used by this command anymore.

Output

The document is compact JSON on a single line (shown split over several lines here). It starts with complete, warnings and temporal, then lists the workflows. Pipe it to jq . to indent it. pendingActivities on an entry is what shows a stuck run.
complete is true when everything was read, and scripts should check only that. warnings is a list of sentences about what is missing, empty when complete is true. Do not parse its wording. Each entry has workflowId, runId, workflowType, status (Temporal’s WORKFLOW_EXECUTION_STATUS_*, null when the workflow was not read), parent (children only), pendingActivities, pendingChildren and events. Events are Temporal’s default JSON form (the one the Temporal UI exports), with payloads decoded to plain JSON, and nothing is added to them. A failed step and its workflow, from a real run, look like this (stack traces and ids shortened):
Event ids restart in every workflow, so identify an event by its entry plus eventId. Related events point at each other through scheduledEventId and startedEventId. The command does not pair events or compute durations, statuses or attempts.

Where the old fields went

What Temporal does not have

Temporal records the workflow’s history, not the trace. These are only in the trace file (logs/runs/ in development, S3 in production) and are not in the new output:
  • Individual LLM and HTTP calls inside a step, with their models, tokens, status codes and timings
  • Cost. Use output workflow cost <workflowId>, which still reads the trace through the API
  • Every failed attempt of a retried activity. Temporal keeps only the last one: attempt and lastFailure (the failure before it) on EVENT_TYPE_ACTIVITY_TASK_STARTED, and on pendingActivities while the step is still retrying

Truncation

Large payloads are cut so a long LLM response does not bury the failure. The limits always apply, there is no flag to lift them, and the full payload stays in Temporal (UI at http://localhost:8080 in development). Error stacks keep their first 10 lines, and error messages are never cut. A payload that cannot be decoded, for example an encrypted one, prints as [Undecodable Payload: <encoding>]. Nothing is redacted. If you have an encryption codec, the codec endpoint of a profile is not used yet.

Long histories and missing children

The run and its children are read to the end. Reading stops after 100,000 events or 1,000 pages (of 1,000 events) across the whole tree, whichever comes first. When it stops early, or when a child’s history is already gone (Temporal deletes closed histories after the namespace retention period), the command still succeeds. complete is false and warnings says what is missing:
A child or later run that cannot be read for another reason, such as a permission or network error, is reported the same way, with the error message in the warning. A workflow that was not read (its history is gone, it could not be read, or the limit was reached first) keeps its entry with events empty, status null and empty pending lists. A workflow cut off in the middle of its history keeps the events read so far, and a warning says it was read only in part. status and the pending lists are read after the events, so they are never older than the events; a workflow that finishes while it is being read gets a warning that its events stop before the end.

Exit codes and errors

A workflow or run that is not found, a Temporal that cannot be reached or does not answer within 30 seconds, a missing --profile or a bad namespace exits 1 with the message on stderr and an empty stdout. This holds with --json too. A partial result (complete is false) exits 0. Scripts that read stdout no longer have to skip the progress lines the old command printed. --run-id reads a run other than the latest. Each reset, retry or continue-as-new has its own run id, and every entry states the run that was read. The runs that continue from it (and those of child workflows) are read too, one entry per run with the same workflowId.

Update scripts and agents

output workflow reset --step still takes the step name. List the names from the scheduled events:
The Output Claude plugin skills describe the new output. Run output update --agents to get them.

Checklist

  • Bump @outputai/core and @outputai/cli to 0.18.0.
  • Make sure the machine that runs output workflow debug reaches your Temporal. For a remote Temporal, add a profile to temporal.toml or set TEMPORAL_ADDRESS, TEMPORAL_NAMESPACE and TEMPORAL_API_KEY.
  • Update scripts, CI jobs and agent skills that parse the old text tree or the trace JSON from --json. Read complete, loop over workflows[].events[], and read steps from EVENT_TYPE_ACTIVITY_TASK_* events.
  • Use workflow cost, or the trace file, when you need LLM and HTTP call detail, cost or full payloads. workflow debug truncates and does not carry them.
  • Handle the exit code and stderr: a failure no longer prints anything to stdout.
  • Pass --run-id when you need a run that is not the latest.