Skip to content

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

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

Open
l2ysho wants to merge 10 commits into
base: master
Choose a base branch
from
Open

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
10f311b
feat(cli): add wait commands and enhance agentic output for builds an…
l2ysho May 29, 2026
46099be
fix(push): exit 0 when build is still RUNNING after wait window
l2ysho May 29, 2026
d2d7038
Merge branch 'master' into 1135-improve-apify-cli-buildrun-output-for…
l2ysho Jun 10, 2026
749fe7e
fix(cli): preserve real job status on wait give-up
l2ysho Jun 15, 2026
3e0ce2d
Merge remote-tracking branch 'origin/1135-improve-apify-cli-buildrun-…
l2ysho Jun 15, 2026
ff41d46
Update src/commands/builds/wait.ts
l2ysho Jun 22, 2026
be2eaa1
Update src/commands/builds/wait.ts
l2ysho Jun 22, 2026
828bcd2
Merge branch 'master' into 1135-improve-apify-cli-buildrun-output-for…
l2ysho Jun 22, 2026
90d1756
style(docs): add period to json flag descriptions
l2ysho Jun 22, 2026
fd3b4fa
Merge remote-tracking branch 'origin/1135-improve-apify-cli-buildrun-…
l2ysho Jun 22, 2026
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
105 changes: 82 additions & 23 deletions docs/reference.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -240,7 +240,7 @@ USAGE
$ apify secrets ls [--json]

FLAGS
--json Format the command output as JSON
--json Format the command output as JSON.
```

##### `apify secrets rm`
Expand Down Expand Up @@ -636,7 +636,7 @@ USAGE

FLAGS
--desc Sort Actors in descending order.
--json Format the command output as JSON
--json Format the command output as JSON.
--limit=<value> Number of Actors that will be listed.
--my Whether to list Actors made by the logged
in user.
Expand Down Expand Up @@ -667,7 +667,7 @@ FLAGS
--category=<value> Filter by category (e.g.
AI).
--json Format the command output as
JSON
JSON.
--limit=<value> Maximum number of results to
return.
--offset=<value> Number of results to skip
Expand Down Expand Up @@ -737,7 +737,7 @@ FLAGS
when the local files are older than the Actor on
the platform.
--json Format the command
output as JSON
output as JSON.
--open Whether to open the
browser automatically to the Actor details page.
-v, --version=<value> Actor version number
Expand Down Expand Up @@ -803,7 +803,7 @@ FLAGS
JSON input to be given to the Actor. The file must be a
valid JSON file. You can also specify `-` to read from
standard input.
--json Format the command output as JSON
--json Format the command output as JSON.
-m, --memory=<value> Amount of memory allocated for
the Actor run, in megabytes.
-o, --output-dataset Prints out the entire default
Expand Down Expand Up @@ -841,7 +841,7 @@ FLAGS
input to be given to the Actor. The file must be a valid
JSON file. You can also specify `-` to read from
standard input.
--json Format the command output as JSON
--json Format the command output as JSON.
-m, --memory=<value> Amount of memory allocated for
the Actor run, in megabytes.
-t, --timeout=<value> Timeout for the Actor run in
Expand All @@ -862,7 +862,7 @@ ARGUMENTS

FLAGS
--input Return the Actor input schema.
--json Format the command output as JSON
--json Format the command output as JSON.
--readme Return the Actor README.
```
<!-- actor-deploy-commands-end -->
Expand All @@ -889,6 +889,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`
Expand All @@ -913,21 +915,23 @@ 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,
it will use the Actor from the current directory.

FLAGS
--json Format the command output as JSON
--json Format the command output as JSON.
--log Whether to print out the build log after
the build is triggered.
--tag=<value> Build tag to be applied to the
successful Actor build. By default, this is "latest".
--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`
Expand All @@ -943,7 +947,7 @@ ARGUMENTS
buildId The build ID to get information about.

FLAGS
--json Format the command output as JSON
--json Format the command output as JSON.
```

##### `apify builds log`
Expand Down Expand Up @@ -976,7 +980,7 @@ ARGUMENTS
FLAGS
-c, --compact Display a compact table.
--desc Sort builds in descending order.
--json Format the command output as JSON
--json Format the command output as JSON.
--limit=<value> Number of builds that will be listed.
--offset=<value> Number of builds that will be skipped.
```
Expand Down Expand Up @@ -1013,6 +1017,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 -->

Expand All @@ -1037,6 +1067,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`
Expand All @@ -1054,7 +1086,7 @@ ARGUMENTS
FLAGS
-f, --force Whether to force the run to abort immediately, instead
of gracefully.
--json Format the command output as JSON
--json Format the command output as JSON.
```

##### `apify runs info`
Expand All @@ -1070,7 +1102,7 @@ ARGUMENTS
runId The run ID to print information about.

FLAGS
--json Format the command output as JSON
--json Format the command output as JSON.
-v, --verbose Prints more in-depth information about the Actor
run.
```
Expand Down Expand Up @@ -1105,7 +1137,7 @@ ARGUMENTS
FLAGS
-c, --compact Display a compact table.
--desc Sort runs in descending order.
--json Format the command output as JSON
--json Format the command output as JSON.
--limit=<value> Number of runs that will be listed.
--offset=<value> Number of runs that will be skipped.
```
Expand All @@ -1123,7 +1155,7 @@ ARGUMENTS
runId The run ID to resurrect.

FLAGS
--json Format the command output as JSON
--json Format the command output as JSON.
```

##### `apify runs rm`
Expand All @@ -1142,6 +1174,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 -->

Expand Down Expand Up @@ -1190,7 +1248,7 @@ ARGUMENTS
datasetName Optional name for the Dataset.

FLAGS
--json Format the command output as JSON
--json Format the command output as JSON.
```

##### `apify datasets get-items`
Expand Down Expand Up @@ -1230,7 +1288,7 @@ ARGUMENTS
storeId The dataset store ID to print information about.

FLAGS
--json Format the command output as JSON
--json Format the command output as JSON.
```

##### `apify datasets ls`
Expand All @@ -1245,7 +1303,7 @@ USAGE

FLAGS
--desc Sorts datasets in descending order.
--json Format the command output as JSON
--json Format the command output as JSON.
--limit=<value> Number of datasets that will be listed.
--offset=<value> Number of datasets that will be skipped.
--unnamed Lists datasets that don't have a name set.
Expand Down Expand Up @@ -1355,7 +1413,7 @@ ARGUMENTS
store.

FLAGS
--json Format the command output as JSON
--json Format the command output as JSON.
```

##### `apify key-value-stores delete-value`
Expand Down Expand Up @@ -1411,7 +1469,7 @@ ARGUMENTS
storeId The key-value store ID to print information about.

FLAGS
--json Format the command output as JSON
--json Format the command output as JSON.
```

##### `apify key-value-stores keys`
Expand All @@ -1432,7 +1490,7 @@ FLAGS
--exclusive-start-key=<value> The key to start
the list from.
--json Format the
command output as JSON
command output as JSON.
--limit=<value> The maximum
number of keys to return.
```
Expand All @@ -1450,7 +1508,7 @@ USAGE
FLAGS
--desc Sorts key-value stores in descending
order.
--json Format the command output as JSON
--json Format the command output as JSON.
--limit=<value> Number of key-value stores that will be
listed.
--offset=<value> Number of key-value stores that will be
Expand Down Expand Up @@ -1564,7 +1622,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
Expand All @@ -1574,6 +1632,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.
Expand Down
2 changes: 2 additions & 0 deletions scripts/generate-cli-docs.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -60,6 +60,7 @@ const categories: Record<string, CommandsInCategory[]> = {
{ command: Commands.buildsLs },
{ command: Commands.buildsRemoveTag },
{ command: Commands.buildsRm },
{ command: Commands.buildsWait },
],
'actor-run': [
//
Expand All @@ -70,6 +71,7 @@ const categories: Record<string, CommandsInCategory[]> = {
{ command: Commands.runsLs },
{ command: Commands.runsResurrect },
{ command: Commands.runsRm },
{ command: Commands.runsWait },
],
'general': [
//
Expand Down
Loading
Loading