Improve Apify CLI build/run output for agentic workflows

[patrikbraborec]

Summary

Agentic workflows rely on terminal output, exit codes, and structured command results. The CLI already exposes most of the information needed to debug Actor builds and runs, but some commands are still easy for agents to misinterpret.

The main problem is that several commands have multiple phases. For example, apify push can successfully create/update an Actor and upload source files, but the cloud build can still fail afterwards. An agent may summarize the earlier phase as success even though the final deployment failed.

The same applies to runs: a run can start successfully, stream logs, and later finish as FAILED, TIMED_OUT, or ABORTED.

Goals

• Make final cloud job status explicit in human-readable output.
• Make --json output reliable for agents.
• Ensure exit code 0 means the relevant waited cloud job actually succeeded.
• Avoid requiring every agent to implement custom polling loops for builds and runs.
• Include concrete IDs and copy-pasteable follow-up commands for async flows.

Non-goals

• Do not add a separate --agent mode for now.
• Focus on improving normal output and --json.

Child issues

• Improve apify push final status and JSON output for agents #1136
• Improve apify call and task run final status and JSON output for agents #1139
• Add wait commands for Actor builds and runs #1140
• Improve apify builds create for async and waited workflows #1138
• Improve apify actors start output for async workflows #1137

Recommended agent contract

For deploy/build:

apify push --json

Agents should only report deploy success if:

ok = true
build.status = SUCCEEDED

For synchronous runs:

apify call --json

Agents should only report run success if:

ok = true
run.status = SUCCEEDED

For async runs:

apify actors start --json
apify runs wait <actual-run-id-from-json> --json

Why this matters

Humans can infer the difference between “Actor uploaded” and “build succeeded” from a full terminal transcript. Agents are more reliable when the CLI gives them explicit final status, structured JSON, concrete IDs, and copy-pasteable next commands.