screenci__screenci/docs/cli.md

title, description

title	description
CLI Commands	Complete reference for the screenci CLI, including recording, testing, upload, project info, and public URL commands.

CLI Commands

The screenci CLI wraps the Playwright workflow used by ScreenCI projects and adds project-aware commands for uploads and public URLs.

Most commands look for screenci.config.ts in the current directory. Use --config <path> when your config lives elsewhere.

Commands overview

Command	What it does
screenci init [name]	Scaffold a new ScreenCI project
screenci test [args...]	Forward directly to playwright test using your ScreenCI config
screenci record [args...]	Record videos with local Playwright
screenci info	Print remote project info as JSON
screenci make-public <videoId>	Enable public URLs for a video
screenci make-private <videoId>	Disable public URLs for a video

screenci init [name]

Creates a new screenci/ directory with a starter config, example video, and optional workflow file. The optional GitHub Actions workflow is written at .github/workflows/screenci.yaml in the current directory. init does not authenticate. If SCREENCI_SECRET is missing, screenci record will open a browser window and complete the login flow before recording starts.

npx screenci@latest init
# or: npx screenci@latest init "My Product"
# or: npx screenci@latest init "My Product" --yes
cd screenci

The optional [name] is the ScreenCI project display name, not the directory name. Because init writes ScreenCI files into screenci/ and the optional workflow into .github/workflows/screenci.yaml, it works well inside existing projects without mixing generated files into your app source.

Options:

• -v, --verbose prints underlying command output instead of spinners
• --install install ScreenCI skills, npm dependencies, and Chromium without prompting
• --ci add GitHub Action CI without prompting
• --skill answer yes to the AI authoring question and include playwright-cli
• -y, --yes answer yes to all init prompts

screenci test [playwrightArgs...]

Forwards Playwright test arguments in normal playwright test syntax while still resolving screenci.config.ts.

npx screenci test
npx screenci test --grep "checkout"
npx screenci test --project=chromium
npx screenci test tests/onboarding.video.ts --grep "step 2"

Use this when you want normal Playwright execution without recording.

To run only some tests, pass the same filters you would use with playwright test, such as a file path or --grep:

npx screenci test videos/onboarding.video.ts
npx screenci test --grep "checkout"
npx screenci test videos/onboarding.video.ts --grep "step 2"

Notes:

• Most arguments after test are passed through as-is to playwright test
• screenci always adds --config <resolved-path-to-screenci.config.ts> for you
• --config / -c are handled by screenci itself, so use them to point to a different screenci.config.ts
• --verbose / -v are also handled by screenci itself for extra CLI logging, not forwarded to Playwright

screenci record [playwrightArgs...]

Records videos with ScreenCI by running local Playwright with SCREENCI_RECORDING=true, then uploads results if SCREENCI_SECRET is set. If the secret is missing, record prompts for login before recording begins.

npx screenci record
npx screenci record --project=chromium

Options:

• -c, --config <path> use a custom config path
• -v, --verbose show full command output during local development setup

Restrictions:

• --workers, -j, --retries, and --fully-parallel are rejected because ScreenCI records sequentially with one worker

screenci info

Fetches the current remote project info for the local projectName and prints it as 2-space-formatted JSON.

npx screenci info

Example output:

{
  "projectName": "my-project",
  "videos": [
    {
      "name": "Onboarding",
      "id": "video_123",
      "isPublic": true,
      "videoURL": "https://api.screenci.com/public/video_123/en/video",
      "thumbnailURL": "https://api.screenci.com/public/video_123/en/thumbnail",
      "subtitlesURL": "https://api.screenci.com/public/video_123/en/subtitle"
    },
    {
      "name": "Settings",
      "id": "video_456",
      "isPublic": false
    }
  ]
}

Requirements:

• SCREENCI_SECRET must be set
• the CLI uses your local projectName from screenci.config.ts

screenci make-public <videoId>

Turns on public URLs for a video and publishes the currently selected versions.

npx screenci make-public video_123

Get <videoId> from screenci info.

Requirements:

• SCREENCI_SECRET must be set
• <videoId> must belong to the organisation associated with that secret

screenci make-private <videoId>

Disables public URLs for a video and removes the public manifest.

npx screenci make-private video_123

Get <videoId> from screenci info.

Requirements:

• SCREENCI_SECRET must be set
• <videoId> must belong to the organisation associated with that secret

Shared --config option

These commands support --config <path>:

• test
• record
• info
• make-public
• make-private

Environment

SCREENCI_SECRET

Used for authenticated ScreenCI API actions:

• upload recordings
• fetch project info
• make videos public
• make videos private

If your config sets envFile, the CLI loads it automatically before these commands run.