---
title: "Actor management · Scrape.ly Docs"
description: "List, search, inspect, call, start, and delete Actors from the terminal."
url: https://scrape.ly/docs/cli-actors
markdown: https://scrape.ly/docs/cli-actors.md
---

# Actor management

> List, search, inspect, call, start, and delete Actors from the terminal.

The `scrapely actors` commands work on Actors on the platform: your own and the public ones in the Store. Use them to list and search Actors, read an Actor's details and input schema, start runs, push, pull, and build, and delete Actors.

## Commands

| Command | Purpose |
| --- | --- |
| `actors ls` | List Actors you created or used |
| `actors search [query]` | Search the public Store |
| `actors info <actorId>` | Show an Actor's details, input schema, or README |
| `actors call [actorId]` | Start a run and wait for it |
| `actors start [actorId]` | Start a run and return immediately |
| `actors push [actorId]` | Push the local project. Same as `scrapely push`. |
| `actors pull [actorId]` | Download an Actor's source. Same as `scrapely pull`. |
| `actors build [actorId]` | Start a build. Same as `scrapely builds create`. |
| `actors rm <actorId>` | Delete an Actor |

An Actor ID can be the opaque ID, `username~actor-name`, or `username/actor-name`.

## List your Actors

```bash
scrapely actors ls
scrapely actors ls --my --desc --limit 20
```

Without `--my`, the list contains Actors you created and Actors you have run. With `--my`, only the ones you created. Each line shows `username/name`, the title, and `public` or `private`.

| Option | Description |
| --- | --- |
| `--my` | Only Actors you created |
| `--limit <number>` | Maximum number to return |
| `--offset <number>` | Number to skip |
| `--desc` | Newest first |
| `--json` | Print the API response, with `total`, `count`, `offset`, `limit`, and `items` |

## Search the Store

```bash
scrapely actors search "google maps"
scrapely actors search --username janedoe --sort-by newest
```

`search` lists public Actors in the Store. It works without logging in. Each result shows the title, `username/name`, a shortened description, the number of users in the last 30 days, and the pricing model.

| Option | Description |
| --- | --- |
| `--category <category>` | Only Actors in this category |
| `--username <username>` | Only Actors by this author |
| `--pricing-model <model>` | `FREE` or `PAY_PER_EVENT` |
| `--sort-by <field>` | `popularity` (default), `newest`, `rating`, `users`, `updated`, or `name`. `relevance` and `lastUpdate` are accepted as aliases. |
| `--limit <number>` | Maximum number of results. Default 20, maximum 100. |
| `--offset <number>` | Number of results to skip |
| `--json` | Print the API response |

To browse the Store in the browser, see [Store](https://scrape.ly/docs/store.md).

## Show an Actor

```bash
scrapely actors info janedoe~my-actor
scrapely actors info janedoe~my-actor --input
scrapely actors info janedoe~my-actor --readme
```

Without options, `info` prints the ID, `username/name`, title, description, visibility, and version numbers (version numbers only for your own Actors).

| Option | Description |
| --- | --- |
| `--input` | Print only the input schema of the build you run, as JSON (the default build for your own Actors, the [User Build](https://scrape.ly/docs/publishing.md#user-build) for others) |
| `--readme` | Print only the README of the build you run |
| `--json` | Print the full Actor object |

`--input` is the quickest way to find out what input an Actor accepts before you call it.

## Start a run and wait

```bash
scrapely actors call janedoe~my-actor -i '{"query":"coffee"}'
scrapely actors call janedoe~my-actor -f input.json -o
scrapely actors call janedoe~my-actor --json -s
```

`actors call` is the same command as `scrapely call`. It starts a run, prints new log output every two seconds until the run ends, and exits with code 1 if the run doesn't end as `SUCCEEDED`. Without an ID it uses `actorId` from the config in the current folder.

| Option | Description |
| --- | --- |
| `-i, --input <json>` | Input as a JSON string |
| `-f, --input-file <path>` | Input from a JSON file, or `-` for stdin |
| `-b, --build <tag>` | Build tag or number to run. Your own Actors only; others run the [User Build](https://scrape.ly/docs/publishing.md#user-build) |
| `-m, --memory <mb>` | Memory for the run, in megabytes |
| `-t, --timeout <seconds>` | Run timeout in seconds. `0` means no timeout. |
| `-o, --output-dataset` | When the run succeeds, print the items of its default dataset as JSON |
| `-s, --silent` | Don't print the run log |
| `--json` | Print `{ "data": <run> }` when the run ends. Implies `--silent` and ignores `-o`. |

Without `-i` or `-f`, the input is `storage/key_value_stores/default/INPUT.json` from the current folder if it exists. Passing both is an error.

The run waits for one of the final statuses: `SUCCEEDED`, `FAILED`, `ABORTED`, or `TIMED-OUT`. A graceful abort in progress (`ABORTING`) keeps the command waiting.

## Start a run

```bash
scrapely actors start janedoe~my-actor -i '{"query":"coffee"}'
RUN_ID=$(scrapely actors start janedoe~my-actor --json | jq -r '.data.id')
```

`start` starts a run and returns as soon as the platform accepts it. It prints the run ID and the first status. Pass the Actor ID: unlike `call`, `start` doesn't read it from the local config.

| Option | Description |
| --- | --- |
| `-i, --input <json>` | Input as a JSON string |
| `-f, --input-file <path>` | Input from a JSON file, or `-` for stdin |
| `-b, --build <tag>` | Build tag or number to run. Your own Actors only; others run the [User Build](https://scrape.ly/docs/publishing.md#user-build) |
| `-m, --memory <mb>` | Memory for the run, in megabytes |
| `-t, --timeout <seconds>` | Run timeout in seconds |
| `--json` | Print `{ "data": <run> }` |

Follow the run with `scrapely runs wait <runId>` or `scrapely runs log <runId>`. See [Runs & builds](https://scrape.ly/docs/cli-runs-builds.md).

## Push, pull, and build

```bash
scrapely actors push
scrapely actors pull janedoe~my-actor --dir ./my-actor
scrapely actors build janedoe~my-actor --version 0.1 --tag beta --wait --log
```

- `actors push` takes the same arguments and options as [`scrapely push`](https://scrape.ly/docs/cli-projects.md#push-to-the-platform).
- `actors pull` is owner only and takes the same arguments and options as [`scrapely pull`](https://scrape.ly/docs/cli-projects.md#pull-from-the-platform).
- `actors build` takes the same arguments and options as [`scrapely builds create`](https://scrape.ly/docs/cli-runs-builds.md#start-a-build).

## Delete an Actor

```bash
scrapely actors rm janedoe~my-actor
scrapely actors rm janedoe~my-actor -y
```

`rm` asks for confirmation unless you pass `-y, --yes`.

## What's next

- [Runs & builds](https://scrape.ly/docs/cli-runs-builds.md): follow, abort, and inspect the runs you start.
- [Run Actors](https://scrape.ly/docs/run-actors.md): run Actors from the dashboard and the API.
- [Actors](https://scrape.ly/docs/actors.md): versions, builds, and the Actor config.

---

- Previous: [Storage management](https://scrape.ly/docs/cli-storage.md)
- Next: [Actor runtime](https://scrape.ly/docs/cli-actor-runtime.md)
- All docs: [Docs index](https://scrape.ly/docs.md), [llms.txt](https://scrape.ly/llms.txt)