CLI

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.

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.

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

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 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
`create`, `templates ls`, `init`, `validate-schema`, `push`, `pull`, `run`, `call`	Create projects, deploy them, and run them locally or on the platform	Projects & running
`actors`	List, search, inspect, start, call, push, pull, build, and delete Actors	Actor management
`runs`, `builds`	Inspect, wait for, abort, resurrect, tag, and delete runs and builds	Runs & builds
`datasets`, `key-value-stores` (alias `kvs`)	Create, read, write, rename, and delete storages	Storage management
`task`	Run, publish, and unpublish saved tasks	Tasks & schedules
`secrets`, `api`	Local secrets for `run`, and raw API requests	Secrets, webhooks & API
`actor`	Runtime commands for use inside a running Actor	Actor runtime
`help`, `upgrade`	Command help, including a version for AI agents, and self-update	Config & troubleshooting

request-queues is registered but has no subcommands yet. Use the request queue API through scrapely api.

The CLI has no commands for schedules or webhooks. Manage them in the dashboard or through the API. Tasks & schedules and Secrets, webhooks & API 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 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: build and run your first Actor.
Authentication: login methods, tokens, the credentials file, and CI.
Projects & running: create, push, pull, and run Actors.
Config & troubleshooting: config files, environment variables, CI/CD, and common errors.