feat(cli): add wait commands and enhance agentic output for builds and runs

docs/reference.md

@@ -69,10 +69,11 @@ ARGUMENTS
 FLAGS
   -d, --body=<value>      The request body (JSON string).
                           Use "-" to read from stdin.
-      --describe=<value>  Describe an endpoint: print every HTTP
-                          method on a path, its summary, and path parameters.
-                          Accepts a path like "actor-runs/{runId}" or
-                          "/v2/actor-runs/{runId}".
+      --describe=<value>  Print a reference for an endpoint
+                          path: its HTTP methods, summary, and path parameters.
+                          Leading slashes and a version prefix in the path are
+                          optional. For example, "actor-runs/{runId}" and
+                          "/v2/actor-runs/{runId}" are both accepted.
       -H, --header=<value>    Additional HTTP header(s). Pass a
                           single "key:value" string, or a JSON object like
                           '{"X-Foo": "bar", "X-Baz": "qux"}' to send multiple
@@ -85,9 +86,11 @@ FLAGS
                           <options: GET|POST|PUT|PATCH|DELETE>
   -p, --params=<value>    Query parameters as a JSON object,
                           e.g. '{"limit": 1, "desc": true}'.
-  -s, --search=<value>    Filter --list-endpoints by a
-                          space-separated query. Each token must appear
-                          (case-insensitive) in method, path, or summary.
+  -s, --search=<value>    Filter results returned by
+                          --list-endpoints. The query is case-insensitive and split
+                          into tokens by spaces. For an endpoint to be returned,
+                          every token must appear in that endpoint's method, path,
+                          or summary.
 ```
 
 ##### `apify telemetry`
@@ -881,6 +884,8 @@ SUBCOMMANDS
   builds log         Prints the log of a specific build.
   builds info        Prints information about a specific build.
   builds create      Creates a new build of the Actor.
+  builds wait        Waits for an Actor build to reach a
+                     terminal status (SUCCEEDED, FAILED, ABORTED, TIMED-OUT).
 ```
 
 ##### `apify builds add-tag`
@@ -905,7 +910,7 @@ DESCRIPTION
 
 USAGE
   $ apify builds create [actorId] [--json] [--log]
-                        [--tag <value>] [--version <value>]
+                        [--tag <value>] [--version <value>] [--wait]
 
 ARGUMENTS
   actorId  Optional Actor ID or Name to trigger a build for. By default,
@@ -920,6 +925,8 @@ FLAGS
       --version=<value>  Optional Actor Version to build. By
                          default, this will be inferred from the tag, but this flag
                          is required when multiple versions have the same tag.
+      --wait             Wait for the build to reach a terminal
+                         status. Returns exit code 0 only when the build SUCCEEDED.
 ```
 
 ##### `apify builds info`
@@ -1005,6 +1012,32 @@ FLAGS
   -y, --yes  Automatic yes to prompts; assume "yes" as answer to all
              prompts.
 ```
+
+##### `apify builds wait`
+
+```sh
+DESCRIPTION
+  Waits for an Actor build to reach a terminal status (SUCCEEDED, FAILED, 
+  ABORTED, TIMED-OUT).
+  Returns exit code 0 only when the build SUCCEEDED. Designed for CI and agentic
+   workflows.
+
+USAGE
+  $ apify builds wait <buildId> [--json]
+                      [--poll-interval <value>] [-t <value>]
+
+ARGUMENTS
+  buildId  The build ID to wait for.
+
+FLAGS
+      --json                   Format the command output as
+                               JSON
+      --poll-interval=<value>  How often to poll the
+                               platform, in seconds. Defaults to 2.
+  -t, --timeout=<value>        Maximum seconds to wait
+                               before giving up. Without this flag the command waits
+                               indefinitely.
+```
 <!-- actor-build-commands-end -->
 <!-- prettier-ignore-end -->
 
@@ -1029,6 +1062,8 @@ SUBCOMMANDS
   runs ls         Lists all runs of the Actor.
   runs resurrect  Resurrects an aborted or finished Actor Run.
   runs rm         Deletes an Actor Run.
+  runs wait       Waits for an Actor run to reach a terminal
+                  status (SUCCEEDED, FAILED, ABORTED, TIMED-OUT).
 ```
 
 ##### `apify runs abort`
@@ -1134,6 +1169,32 @@ FLAGS
   -y, --yes  Automatic yes to prompts; assume "yes" as answer to all
              prompts.
 ```
+
+##### `apify runs wait`
+
+```sh
+DESCRIPTION
+  Waits for an Actor run to reach a terminal status (SUCCEEDED, FAILED, ABORTED,
+   TIMED-OUT).
+  Returns exit code 0 only when the run SUCCEEDED. Designed for CI and agentic 
+  workflows.
+
+USAGE
+  $ apify runs wait <runId> [--json] [--poll-interval <value>]
+                    [-t <value>]
+
+ARGUMENTS
+  runId  The run ID to wait for.
+
+FLAGS
+      --json                   Format the command output as
+                               JSON
+      --poll-interval=<value>  How often to poll the
+                               platform, in seconds. Defaults to 2.
+  -t, --timeout=<value>        Maximum seconds to wait
+                               before giving up. Without this flag the command waits
+                               indefinitely.
+```
 <!-- actor-run-commands-end -->
 <!-- prettier-ignore-end -->
 
@@ -1556,7 +1617,7 @@ DESCRIPTION
   Customize with --memory and --timeout flags.
 
 USAGE
-  $ apify task run <taskId> [-b <value>] [-m <value>]
+  $ apify task run <taskId> [-b <value>] [--json] [-m <value>]
                    [-t <value>]
 
 ARGUMENTS
@@ -1566,6 +1627,7 @@ ARGUMENTS
 FLAGS
   -b, --build=<value>    Tag or number of the build to run
                          (e.g. "latest" or "1.2.34").
+      --json             Format the command output as JSON
   -m, --memory=<value>   Amount of memory allocated for the
                          Task run, in megabytes.
   -t, --timeout=<value>  Timeout for the Task run in seconds.

scripts/generate-cli-docs.ts

@@ -60,6 +60,7 @@ const categories: Record<string, CommandsInCategory[]> = {
 		{ command: Commands.buildsLs },
 		{ command: Commands.buildsRemoveTag },
 		{ command: Commands.buildsRm },
+		{ command: Commands.buildsWait },
 	],
 	'actor-run': [
 		//
@@ -70,6 +71,7 @@ const categories: Record<string, CommandsInCategory[]> = {
 		{ command: Commands.runsLs },
 		{ command: Commands.runsResurrect },
 		{ command: Commands.runsRm },
+		{ command: Commands.runsWait },
 	],
 	'general': [
 		//

src/commands/actors/call.ts

@@ -13,6 +13,13 @@ import chalk from 'chalk';
 import { ApifyCommand, StdinMode } from '../../lib/command-framework/apify-command.js';
 import { Args } from '../../lib/command-framework/args.js';
 import { Flags } from '../../lib/command-framework/flags.js';
+import {
+	consoleDatasetUrl,
+	consoleRunUrl,
+	exitCodeForJobStatus,
+	fetchLogTail,
+	formatResultSummary,
+} from '../../lib/commands/agent-output.js';
 import { getInputOverride } from '../../lib/commands/resolve-input.js';
 import { runActorOrTaskOnCloud, SharedRunOnCloudFlags } from '../../lib/commands/run-on-cloud.js';
 import { CommandExitCodes, LOCAL_CONFIG_PATH } from '../../lib/consts.js';
@@ -144,10 +151,7 @@ export class ActorsCallCommand extends ApifyCommand<typeof ActorsCallCommand> {
 		}
 
 		let runStarted = false;
-		let run: ActorRun;
-
-		let url: string;
-		let datasetUrl: string;
+		let run: ActorRun | undefined;
 
 		const iterator = runActorOrTaskOnCloud(apifyClient, {
 			actorOrTaskData: {
@@ -160,6 +164,7 @@ export class ActorsCallCommand extends ApifyCommand<typeof ActorsCallCommand> {
 			silent: this.flags.silent,
 			waitForRunToFinish: true,
 			printRunLogs: true,
+			suppressFinalStatus: true,
 		});
 
 		for await (const yieldedRun of iterator) {
@@ -170,8 +175,7 @@ export class ActorsCallCommand extends ApifyCommand<typeof ActorsCallCommand> {
 
 				// A *lot* is copied from `runs info`
 				if (!this.flags.silent) {
-					url = `https://console.apify.com/actors/${actorId}/runs/${yieldedRun.id}`;
-					datasetUrl = `https://console.apify.com/storage/datasets/${yieldedRun.defaultDatasetId}`;
+					const startedUrl = `https://console.apify.com/actors/${actorId}/runs/${yieldedRun.id}`;
 
 					const message: string[] = [`${chalk.yellow('Started')}: ${TimestampFormatter.display(yieldedRun.startedAt)}`];
 
@@ -213,29 +217,87 @@ export class ActorsCallCommand extends ApifyCommand<typeof ActorsCallCommand> {
 					message.push(`${chalk.yellow('Memory')}: ${run.options.memoryMbytes} MB`);
 
 					// url
-					message.push(`${chalk.blue('View on Apify Console')}: ${url}`, '');
+					message.push(`${chalk.blue('View on Apify Console')}: ${startedUrl}`, '');
 
 					simpleLog({ message: message.join('\n'), stdout: !this.flags.json });
 				}
 			}
 		}
 
+		if (!run) {
+			error({ message: 'Actor run did not start.' });
+			process.exitCode = CommandExitCodes.RunFailed;
+			return;
+		}
+		const finalRun = run;
+		const finalUrl = consoleRunUrl(actorId, finalRun.id);
+		const finalDatasetUrl = consoleDatasetUrl(finalRun.defaultDatasetId);
+		const ok = finalRun.status === 'SUCCEEDED';
+		const exitCode = exitCodeForJobStatus(finalRun.status, 'run');
+		const logTail = ok ? [] : await fetchLogTail(apifyClient, finalRun.id);
+
 		if (this.flags.json) {
-			printJsonToStdout(run!);
+			printJsonToStdout({
+				ok,
+				operation: 'call',
+				actor: {
+					id: actorId,
+					url: `https://console.apify.com/actors/${actorId}`,
+				},
+				run: {
+					id: finalRun.id,
+					status: finalRun.status,
+					exitCode: finalRun.exitCode ?? null,
+					url: finalUrl,
+				},
+				storage: {
+					defaultDatasetId: finalRun.defaultDatasetId,
+					defaultKeyValueStoreId: finalRun.defaultKeyValueStoreId,
+					datasetUrl: finalDatasetUrl,
+				},
+				...(ok
+					? {}
+					: {
+							error: {
+								phase: 'run',
+								message: 'Actor run did not succeed',
+								logTail,
+							},
+						}),
+				exitCode,
+			});
+			process.exitCode = exitCode;
 			return;
 		}
 
 		if (!this.flags.silent) {
 			simpleLog({
-				message: [
-					'',
-					`${chalk.blue('Export results')}: ${datasetUrl!}`,
-					`${chalk.blue('View on Apify Console')}: ${url!}`,
-				].join('\n'),
+				message: formatResultSummary({
+					resultLabel: 'Apify call result',
+					overallStatus: finalRun.status as never,
+					lines: [
+						{ label: 'Run', value: finalRun.status as string },
+						{ label: 'Actor ID', value: actorId },
+						{ label: 'Run ID', value: finalRun.id },
+						{ label: 'Build number', value: finalRun.buildNumber },
+						...(typeof finalRun.exitCode === 'number'
+							? [{ label: 'Exit code', value: String(finalRun.exitCode) }]
+							: []),
+						{ label: 'Dataset ID', value: finalRun.defaultDatasetId },
+						{ label: 'Key-value store ID', value: finalRun.defaultKeyValueStoreId },
+					],
+					links: [
+						{ label: 'Run URL', url: finalUrl },
+						{ label: 'Dataset URL', url: finalDatasetUrl },
+					],
+					errorReason: ok ? undefined : logTail,
+				}),
 				stdout: true,
 			});
 		}
 
+		process.exitCode = exitCode;
+
 		if (this.flags.outputDataset) {
 			const datasetId = run!.defaultDatasetId;