Authentication

The CLI sends a bearer token with every API request. You can log in once on your machine and let the CLI store the token, or set SCRAPELY_TOKEN in CI. This page covers the login methods, where credentials are stored, and the order in which the CLI resolves the token and the API URL.

Log in

scrapely login

scrapely auth login does the same thing.

On an interactive terminal with neither option, the CLI asks you to choose a method:

On a terminal that isn't interactive, login without --token uses the console method. Use --token or SCRAPELY_TOKEN in scripts.

If you are already logged in, login asks whether to log in with a different account. --token skips that question.

The CLI validates the token with GET /v2/users/me, then writes the token, the API URL it used, and your user details to ~/.scrapely/credentials.json.

Browser tokens and API keys

The two kinds of token behave differently:

• Browser login stores an OAuth access token. It expires, by default after 24 hours, and then commands fail with an authentication error until you log in again. It can't read or reset your API key.
• API keys from Settings → API & Integrations don't expire. Use one for CI, servers, and anything long-running, with scrapely login --token or SCRAPELY_TOKEN.

scrapely login accepts any API key, including a scoped key you created under Settings → API keys: it only checks the key with GET /v2/users/me. Commands then succeed or fail according to the key's scopes. For CI, prefer a scoped key, for example actors:build + actors:read for deploys. See API keys & permissions.

Check the account

scrapely info

info fetches your account from the API and prints the username, email, user ID, plan, and the API URL in use. It also refreshes the cached user details in credentials.json. If the API can't be reached, it prints the cached details with a warning that they may be stale.

To print the stored token, for example to pass it to another tool:

scrapely auth token

auth token fails if you are not logged in. Treat its output as a secret: it gives full access to your account.

Log out

scrapely logout

scrapely auth logout does the same thing. Both empty ~/.scrapely/credentials.json. If no token is stored, they print Not logged in.

Logging out does not revoke the token. To invalidate an API key, reset it in the dashboard or call POST /v2/api-keys/reset with your API key. A browser login token expires on its own.

The auth group

Credentials and precedence

The CLI keeps its state in ~/.scrapely/. Both files are written with mode 0600.

The token comes from the first of:

1. The token saved in ~/.scrapely/credentials.json
2. SCRAPELY_TOKEN

The API URL comes from the first of:

1. SCRAPELY_API_BASE_URL
2. SCRAPELY_API_URL
3. The API URL saved in ~/.scrapely/credentials.json
4. The built-in default

The dashboard URL used in printed links and by push --open comes from SCRAPELY_WEB_URL. Without it, the CLI derives one from the API URL, which doesn't give the right dashboard address for production. Set SCRAPELY_WEB_URL=https://my.scrape.ly.

Commands that need authentication fail with You are not logged in. Call "scrapely login" first. when no token is available. actors search and templates ls work without logging in.

CI and other non-interactive use

Set an API key in the environment. Don't run scrapely login in the pipeline.

export SCRAPELY_API_URL=https://api.scrape.ly
export SCRAPELY_TOKEN=<your API key>
scrapely push --wait-for-finish 600

In GitHub Actions:

- name: Deploy
  env:
    SCRAPELY_API_URL: https://api.scrape.ly
    SCRAPELY_TOKEN: ${{ secrets.SCRAPELY_TOKEN }}
  run: scrapely push --wait-for-finish 600

Keep the key in your CI provider's secret store, never in the repository. Pass -y to delete commands so nothing waits on a prompt. More pipeline examples are in Config & troubleshooting.

Tokens inside an Actor container

The scrapely actor runtime commands resolve credentials differently, because the platform gives each run its own environment.

The token comes from the first of ACTOR_TOKEN, APIFY_TOKEN, SCRAPELY_TOKEN, and the saved token. The API URL comes from the first of APIFY_API_BASE_URL, SCRAPELY_API_BASE_URL, SCRAPELY_API_URL, and the saved API URL.

If any of those API URL variables is set, the saved token is never used. A container that has an API URL but no token can't act with the account saved on the machine. See Actor runtime.

What's next

• Actor runtime: the commands and variables inside a container.
• Config & troubleshooting: pipelines and common authentication errors.
• Account: create and reset API keys in the dashboard.
• API keys & permissions: scoped keys, expiry, and limits.
• Security: how tokens and permissions work.