---
title: "CLI reference · Scrape.ly Docs"
description: "Install the Scrape.ly CLI and see every command at a glance."
url: https://scrape.ly/docs/cli
markdown: https://scrape.ly/docs/cli.md
---

# CLI reference

> Install the Scrape.ly CLI and see every command at a glance.

The Scrape.ly CLI is the terminal client for the platform. Use it to log in, create Actor projects from templates, push and build them, start runs and read their results, manage datasets and key-value stores, and call any API endpoint. Inside an Actor container, the same binary reads input and writes results for the current run.

The source code is on GitHub: [scrapely-app/scrapely-cli](https://github.com/scrapely-app/scrapely-cli).

## Install

The CLI is published as `scrapely-cli` and installs the `scrapely` executable. It needs Node.js 20.17 or newer.

```bash
npm install -g scrapely-cli
scrapely --version
```

To run a command without a global install, use npx:

```bash
npx scrapely-cli --help
```

To update an existing install, run `scrapely upgrade`. See [Config & troubleshooting](https://scrape.ly/docs/cli-config.md#upgrade-the-cli).

## Choose the API

Before you log in for the first time, point the CLI at production:

```bash
export SCRAPELY_API_URL=https://api.scrape.ly
export SCRAPELY_WEB_URL=https://my.scrape.ly
```

> [!WARNING]
> Without `SCRAPELY_API_URL` (or `SCRAPELY_API_BASE_URL`), and with no API URL saved from an earlier login, the CLI uses its built-in default, which is not the production API. `scrapely login` prints the URL it is using. `SCRAPELY_WEB_URL` sets the dashboard address used in the links the CLI prints and by `push --open`.

## Log in

```bash
scrapely login
```

On an interactive terminal the CLI asks you to choose a method. **Browser** opens the dashboard, asks you to approve the CLI, and receives a token on a local callback. **Console** opens the dashboard so you can copy an API key from **Settings → API & Integrations** and paste it. **Manual** asks you to paste a key. To skip the prompt, pass `--method` or a token:

```bash
scrapely login --method browser
scrapely login --token "$SCRAPELY_TOKEN"
```

The CLI validates the token with `GET /v2/users/me` and saves it, with the API URL and your user details, to `~/.scrapely/credentials.json`. Check the result with `scrapely info`.

For CI and other non-interactive environments, set `SCRAPELY_TOKEN` to an API key instead of logging in. See [Authentication](https://scrape.ly/docs/cli-auth.md) for the methods, the files, and the precedence rules.

## Global options

| Option | Description |
| --- | --- |
| `-v, --version` | Print the CLI version |
| `-h, --help` | Print help for the CLI, or for any command when given after it |

Everything else is defined per command. `scrapely help <command>` prints the help for one command, including nested ones such as `scrapely help "actors ls"`.

## Commands

| Commands | What they do | Reference |
| --- | --- | --- |
| `login`, `logout`, `info`, `auth login`, `auth logout`, `auth token` | Log in, log out, and show the account and token | [Authentication](https://scrape.ly/docs/cli-auth.md) |
| `create`, `templates ls`, `init`, `validate-schema`, `push`, `pull`, `run`, `call` | Create projects, deploy them, and run them locally or on the platform | [Projects & running](https://scrape.ly/docs/cli-projects.md) |
| `actors` | List, search, inspect, start, call, push, pull, build, and delete Actors | [Actor management](https://scrape.ly/docs/cli-actors.md) |
| `runs`, `builds` | Inspect, wait for, abort, resurrect, tag, and delete runs and builds | [Runs & builds](https://scrape.ly/docs/cli-runs-builds.md) |
| `datasets`, `key-value-stores` (alias `kvs`) | Create, read, write, rename, and delete storages | [Storage management](https://scrape.ly/docs/cli-storage.md) |
| `task` | Run, publish, and unpublish saved tasks | [Tasks & schedules](https://scrape.ly/docs/cli-tasks-schedules.md) |
| `secrets`, `api` | Local secrets for `run`, and raw API requests | [Secrets, webhooks & API](https://scrape.ly/docs/cli-webhooks-secrets.md) |
| `actor` | Runtime commands for use inside a running Actor | [Actor runtime](https://scrape.ly/docs/cli-actor-runtime.md) |
| `help`, `upgrade` | Command help, including a version for AI agents, and self-update | [Config & troubleshooting](https://scrape.ly/docs/cli-config.md) |

`request-queues` is registered but has no subcommands yet. Use the [request queue API](https://scrape.ly/docs/api-request-queues.md) through `scrapely api`.

The CLI has no commands for schedules or webhooks. Manage them in the dashboard or through the API. [Tasks & schedules](https://scrape.ly/docs/cli-tasks-schedules.md) and [Secrets, webhooks & API](https://scrape.ly/docs/cli-webhooks-secrets.md) show the `scrapely api` calls.

Two pairs of names are easy to confuse:

- `scrapely actors` manages Actors in your account from your machine. `scrapely actor` runs inside an Actor container and acts on the current run.
- `scrapely run` runs the project in the current folder on your machine. `scrapely call` starts a run on the platform and waits for it.

## A first deployment

```bash
scrapely login
scrapely create my-actor --template crawlee-cheerio-js
cd my-actor
scrapely push
scrapely call -i '{"startUrls":[{"url":"https://crawlee.dev"}]}' -o
```

`push` creates the Actor, uploads the source, and waits for the build. `call` runs it on the platform, streams the log, and with `-o` prints the dataset items. The [Quick start](https://scrape.ly/docs/quickstart.md) explains each step.

## Conventions

**Actor IDs.** Where a command takes an Actor ID, you can pass the opaque ID, `username~actor-name`, or `username/actor-name`. In a project folder, `push`, `call`, `actors call`, `runs ls`, and `builds ls` default to the Actor in the folder's config file.

**Storage names.** Dataset and key-value store commands accept a storage ID or the name of one of your named storages.

**Confirmation prompts.** Commands that delete something prompt first. Pass `-y, --yes` to skip the prompt in scripts. `secrets rm` does not prompt.

**JSON output.** Commands with `--json` print machine-readable JSON instead of formatted text. Most print the API object, some wrap it as `{ "data": … }`. Each command page shows the shape.

**Exit codes.** A failed command exits with a non-zero code. So do `call`, `actors call`, `runs wait`, and `builds wait` when the run or build ends in any status other than `SUCCEEDED`, and `push` when the build fails.

**Reading from stdin.** `datasets push-items` and `actor push-data` read the item from stdin when you omit it. `call`, `actors call`, `actors start`, and `run` read input from stdin with `-f -`. `api` reads the request body from stdin with `-d -`.

**Default input.** When you don't pass `-i` or `-f`, `call`, `actors call`, `actors start`, `task run`, and `run` use `storage/key_value_stores/default/INPUT.json` from the current folder, if it exists.

## What's next

- [Quick start](https://scrape.ly/docs/quickstart.md): build and run your first Actor.
- [Authentication](https://scrape.ly/docs/cli-auth.md): login methods, tokens, the credentials file, and CI.
- [Projects & running](https://scrape.ly/docs/cli-projects.md): create, push, pull, and run Actors.
- [Config & troubleshooting](https://scrape.ly/docs/cli-config.md): config files, environment variables, CI/CD, and common errors.

---

- Previous: [API reference](https://scrape.ly/docs/sdk-python-reference.md)
- Next: [Authentication](https://scrape.ly/docs/cli-auth.md)
- All docs: [Docs index](https://scrape.ly/docs.md), [llms.txt](https://scrape.ly/llms.txt)