CLI login & API access

Signing in ties your recordings to your screencli account and workspace — they show up on your dashboard, draw on your plan and credits, and become reachable through the API. The same token authenticates the CLI, a CI job, and any direct API call, so you log in once and reuse it everywhere.

Sign in from the terminal

npx screencli login

This opens your browser to sign in to your screencli account (GitHub or Google). Once you approve, you're redirected back to the CLI and the token is saved to ~/.screencli/config.json — every later record, verify, or export uses it automatically.

Under the hood, login starts a tiny local server on a free port and opens https://screencli.sh/api/cli-callback?port=<port>. If you're already signed in on that browser, screencli mints an API key for the CLI and redirects to http://localhost:<port>/callback with the token and your email. If you're not signed in, you're sent to the login screen first and returned to the same callback once you are — so a fresh machine just needs one browser sign-in.

You don't have to log in to try screencli: the very first npx screencli record works with no account and still gives you a shareable link (see Use the CLI). Log in when you want those recordings on your dashboard, shared with your team, and counted under one plan.

Reuse the token in CI

For a GitHub Action or any non-interactive job, print the saved token and store it as a secret rather than running login in the pipeline:

npx screencli token

Copy the value into a repository secret (for example Settings → Secrets and variables → Actions → New repository secret, named SCREENCLI_TOKEN), then expose it to the CLI as an environment variable:

# .github/workflows/demo.yml
- name: Record a demo
  env:
    SCREENCLI_TOKEN: ${{ secrets.SCREENCLI_TOKEN }}
  run: npx screencli record https://staging.example.com -p "Walk through the main features"

The token is a long-lived API key — it has no expiry — so a stored secret keeps working until you rotate it.

The API key

login mints a Better Auth API key on the server. What that means in practice:

It's prefixed sc — the value starts with sc. Treat it as a password: it grants full access to your account's recordings.
No expiry. The key stays valid until it's deleted, which is why it's safe to bake into a CI secret.
High rate limit — 10,000 requests per day, so normal CLI and API use never hits it.
One key per login. Each npx screencli login creates a fresh key named cli; screencli also mints short-lived sandbox-auto keys internally when it dispatches a cloud run on your behalf.

Send it as a bearer token on any API request:

Authorization: Bearer sc...your_token_here

Call the API directly

Every screencli surface — the CLI, the dashboard composer, and the GitHub App — talks to the same HTTP API at https://screencli.sh. You can call it yourself with your sc key. Requests authenticate with either the bearer token above or a browser session cookie (what the dashboard uses); the token is the right choice for scripts.

Method & path	What it does	Auth
`GET /api/recordings`	List every recording visible to you — your own plus your workspace's.	Required
`GET /api/recordings/:id`	Fetch one recording's detail (metadata, verdict, chapters). Accepts the full UUID or the short ID. Public if the recording's visibility allows it.	Optional
`POST /api/recordings`	Register a recording and get back the upload URLs (the CLI uses this to start an upload).	Required
`PUT /api/recordings/:id/upload/:type`	Upload a file for a recording — `type` is `raw`, `events`, `video`, or `thumbnail`.	Required
`POST /api/recordings/:id/confirm`	Finalize a recording once its files are uploaded.	Required
`DELETE /api/recordings/:id`	Delete a recording you own — removes the video, thumbnail, and record.	Required (owner)
`GET /api/recordings/:id/video`	Stream the composed MP4. Public for shareable links — this is what the watch page plays.	None
`GET /api/recordings/:id/thumbnail`	The recording's thumbnail image.	Follows visibility
`GET /api/health`	Liveness check — returns `{ "status": "ok" }`.	None

Example — list your recordings

curl https://screencli.sh/api/recordings \
  -H "Authorization: Bearer $SCREENCLI_TOKEN"

{
  "recordings": [
    {
      "id": "8f3c1e2a-…",
      "title": "Sign in and confirm the dashboard loads",
      "url": "https://staging.example.com",
      "status": "ready",
      "visibility": "public",
      "durationMs": 14200,
      "createdAt": "2026-07-25T18:04:11.000Z"
    }
  ]
}

Results are ordered newest first and scoped to what your account can see — your recordings plus any created by teammates in your workspace.

Notes & limits

The token is the whole identity. Anyone holding your sc key can list, read, and delete your recordings. Keep it in a secret store, not in source.
Public GETs are intentional. GET /api/recordings/:id/video (and the watch page it powers) serve without auth so share links work for anyone — but only for recordings whose visibility is public or unlisted. private recordings 404 for non-members.
First run needs no key. Anonymous record still produces a public link; logging in is what attaches recordings to your account and plan. See Use the CLI.
Rotating the key. Running npx screencli login again mints a new key; update any SCREENCLI_TOKEN secret that used the old one.