--- title: "Runs & builds · Scrape.ly Docs" description: "Follow, wait for, abort, and manage runs and builds." url: https://scrape.ly/docs/cli-runs-builds markdown: https://scrape.ly/docs/cli-runs-builds.md --- # Runs & builds > Follow, wait for, abort, and manage runs and builds. A build turns one version of an Actor's source into a Docker image. A run executes a build. The `scrapely runs` and `scrapely builds` commands list, inspect, wait for, and clean up both, and `builds` also starts builds and manages build tags. ## Runs | Command | Purpose | | --- | --- | | `runs ls [actorId]` | List runs | | `runs info ` | Show a run's status and storage IDs | | `runs log ` | Print a run's log | | `runs wait ` | Wait until a run finishes | | `runs abort ` | Abort a run | | `runs resurrect ` | Restart a finished run | | `runs rm ` | Delete a run | ### List runs ```bash scrapely runs ls scrapely runs ls janedoe~my-actor --desc --limit 10 ``` Without an Actor ID, `runs ls` lists the runs of the Actor in the current folder's config (its `actorId`, or else its `name`). Outside a project folder it lists all your runs. Each line shows the run ID, the status, and the exit code if there is one. | Option | Description | | --- | --- | | `--limit ` | Maximum number to return | | `--offset ` | Number to skip | | `--desc` | Newest first | | `-c, --compact` | One line per run, without indentation | | `--json` | Print the API response | ### Inspect a run ```bash scrapely runs info scrapely runs info --verbose scrapely runs log ``` `runs info` prints the ID, status, exit code, `Dataset ID`, and `KVS ID`. Use the dataset ID with `scrapely datasets get-items` to read the results. | Option | Description | | --- | --- | | `-v, --verbose` | Also print every field of the run object | | `--json` | Print `{ "data": }` | `runs log` prints the full log once. When the log has expired under the data-retention policy, it says so. To follow a run as it happens, start it with `scrapely call`, which streams the log. ### Wait for a run ```bash scrapely runs wait scrapely runs wait --timeout 600 --poll-interval 5 --json ``` `runs wait` checks the run's status until it reaches `SUCCEEDED`, `FAILED`, `ABORTED`, or `TIMED-OUT`. It exits with code 0 for `SUCCEEDED` and 1 for anything else. | Option | Description | | --- | --- | | `-t, --timeout ` | Give up after this many seconds and exit with code 1. Default `0`, no limit. | | `--poll-interval ` | Seconds between checks. Default `2`. | | `--json` | Print `{ "runId": …, "status": … }` | ### Abort, resurrect, and delete ```bash scrapely runs abort scrapely runs abort --force scrapely runs resurrect scrapely runs rm -y ``` `runs abort` asks the run to stop gracefully, so the Actor gets the chance to save its state. `-f, --force` stops it immediately. `--json` prints `{ "data": }` after the abort request. `runs resurrect` restarts a finished run with the same storages, so it can continue where it stopped. It prints the new status, or `{ "data": }` with `--json`. `runs rm` deletes a run. It asks for confirmation unless you pass `-y, --yes`. ### Run statuses | Status | Meaning | | --- | --- | | `READY` | Accepted and waiting for capacity | | `RUNNING` | Executing | | `SUCCEEDED` | Finished with exit code 0 | | `FAILED` | Finished with a non-zero exit code or an error | | `ABORTING` | Graceful abort in progress | | `ABORTED` | Stopped by an abort | | `TIMING-OUT` | The timeout was reached and the run is stopping | | `TIMED-OUT` | Stopped by the timeout | ## Builds | Command | Purpose | | --- | --- | | `builds ls [actorId]` | List builds | | `builds info ` | Show a build | | `builds log ` | Print a build's log | | `builds wait ` | Wait until a build finishes | | `builds create [actorId]` | Start a build | | `builds add-tag` | Point a tag at a build | | `builds remove-tag` | Remove a tag from a build | | `builds rm ` | Delete a build | Builds are owner only, also for public Actors. On someone else's Actor, these commands fail: `403` for an Actor's builds, `404` for a build ID. `scrapely push` already starts a build after every upload. Use `builds create` to rebuild a version without uploading again. ### List and inspect builds ```bash scrapely builds ls scrapely builds ls janedoe~my-actor --desc scrapely builds info scrapely builds log ``` Without an Actor ID, `builds ls` lists the builds of the Actor in the current folder's config. Outside a project folder it lists all your builds. Each line shows the build ID, the build number, and the status. | Option | Description | | --- | --- | | `--limit ` | Maximum number to return | | `--offset ` | Number to skip | | `--desc` | Newest first | | `-c, --compact` | Print only the build IDs, one per line | | `--json` | Print the API response | `builds info` prints the ID, build number, status, exit code, and start and finish times. `--json` prints the build object. ### Wait for a build ```bash scrapely builds wait --timeout 900 ``` `builds wait` checks the build's status while it is `RUNNING` and exits with code 0 if the build `SUCCEEDED`, 1 otherwise. It takes the same `-t, --timeout`, `--poll-interval`, and `--json` options as `runs wait`. On timeout, `--json` prints `"status": "TIMEOUT"`. ### Start a build ```bash scrapely builds create scrapely builds create janedoe~my-actor --version 0.1 --tag beta --wait --log ``` `builds create` builds one version of the Actor without the Docker cache. Without an Actor ID it uses `actorId` from the config in the current folder. `scrapely actors build` is the same command. | Option | Description | | --- | --- | | `--version ` | Version to build. Default: `version` from the local config, then `0.0.1`. | | `--tag ` | Tag to give the build when it succeeds | | `--wait` | Wait for the build to finish | | `--log` | Print the build log afterwards | | `--json` | Print `{ "data": }` with the build's status | > [!WARNING] > When you pass an Actor ID, the default version doesn't come from the Actor on the platform. Outside a project folder it is `0.0.1`, so pass `--version` for Actors created by `scrapely push`, whose first version is `0.0`. > [!WARNING] > With `--json`, the command exits with code 1 unless the build has `SUCCEEDED`. Combine `--json` with `--wait`, otherwise the build is still running when the command returns and the exit code is 1. ### Tag builds A build tag is a name, such as `latest` or `beta`, that points to one build of the Actor. A run started without `-b` uses the `latest` tag. ```bash scrapely builds add-tag -b -t beta scrapely builds remove-tag -b -t beta ``` | Option | Description | | --- | --- | | `-b, --build ` | Build ID. Required. | | `-t, --tag ` | Tag name. Required. | | `-y, --yes` | `remove-tag` only: don't ask for confirmation | `add-tag` only tags builds that have `SUCCEEDED`. If the tag already points to another build, it moves to this one. `remove-tag` fails unless the tag currently points to the build you name. ### Delete a build ```bash scrapely builds rm scrapely builds rm -y ``` `builds rm` asks for confirmation unless you pass `-y, --yes`. The Actor's current [User Build](https://scrape.ly/docs/publishing.md#user-build) can't be deleted; set a different one first. ### Build statuses | Status | Meaning | | --- | --- | | `READY` | Waiting to start | | `RUNNING` | Building | | `SUCCEEDED` | The image is ready to run | | `FAILED` | The build failed. Read the log with `builds log`. | | `TIMED-OUT` | The build took too long | | `ABORTED` | The build was stopped | ## What's next - [Storage management](https://scrape.ly/docs/cli-storage.md): read the datasets and key-value stores your runs produce. - [Actors](https://scrape.ly/docs/actors.md): how versions, builds, tags, and runs fit together. - [Runs API](https://scrape.ly/docs/api-runs.md): the endpoints these commands use. --- - Previous: [Actor runtime](https://scrape.ly/docs/cli-actor-runtime.md) - Next: [Tasks & schedules](https://scrape.ly/docs/cli-tasks-schedules.md) - All docs: [Docs index](https://scrape.ly/docs.md), [llms.txt](https://scrape.ly/llms.txt)