mirror of
https://github.com/screenci/screenci.git
synced 2026-09-19 08:57:46 +08:00
Olli Paloviita
401 lines
9.0 KiB
Plaintext
401 lines
9.0 KiB
Plaintext
# CLI
|
|
|
|
import { Tabs, TabItem } from '@astrojs/starlight/components'
|
|
|
|
The `screenci` CLI keeps the workflow small: initialize a project, iterate
|
|
locally, record final output, and manage public delivery when needed. Most
|
|
commands resolve `screenci.config.ts` from the current directory unless you
|
|
pass `--config <path>`.
|
|
|
|
## Command overview
|
|
|
|
| Command | Purpose |
|
|
| ---------------------------------- | ----------------------------------------------------- |
|
|
| `screenci init [name]` | Scaffold a ScreenCI project |
|
|
| `screenci test [playwrightArgs]` | Run `.video.ts` files locally without final recording |
|
|
| `screenci record [playwrightArgs]` | Record videos and upload results when configured |
|
|
| `screenci info` | Print remote project info as JSON |
|
|
| `screenci make-public <videoId>` | Enable public delivery for a video |
|
|
| `screenci make-private <videoId>` | Disable public delivery for a video |
|
|
|
|
## `screenci init [name]`
|
|
|
|
Create a new ScreenCI project in the current directory:
|
|
|
|
<Tabs syncKey="package-manager">
|
|
<TabItem label="npm">
|
|
|
|
```bash
|
|
npm init screenci@latest
|
|
npm init screenci@latest my-product
|
|
```
|
|
|
|
</TabItem>
|
|
<TabItem label="pnpm">
|
|
|
|
```bash
|
|
pnpm create screenci
|
|
pnpm create screenci my-product
|
|
```
|
|
|
|
</TabItem>
|
|
<TabItem label="yarn">
|
|
|
|
```bash
|
|
yarn create screenci
|
|
yarn create screenci my-product
|
|
```
|
|
|
|
</TabItem>
|
|
</Tabs>
|
|
|
|
When using `npm init`, pass extra initializer flags after `--`:
|
|
|
|
```bash
|
|
npm init screenci@latest -- --yes --package-manager pnpm
|
|
npm init screenci@latest -- --yes --package-manager yarn
|
|
```
|
|
|
|
The package manager is auto-detected from the `npm_config_user_agent` environment
|
|
variable (set automatically when you run `pnpm create` or `yarn create`), lockfile
|
|
presence (`pnpm-lock.yaml`, `yarn.lock`), or the `packageManager` field in
|
|
`package.json`. Use `--package-manager` to override.
|
|
|
|
Common options:
|
|
|
|
- `-y, --yes` accepts all defaults
|
|
- `--package-manager <npm|pnpm|yarn>` overrides auto-detected package manager
|
|
- `--agent <name>` passes an agent name to the selected skills install command
|
|
- `-v, --verbose` prints underlying command output
|
|
|
|
Interactive defaults create the GitHub Actions workflow, install
|
|
dependencies, install Chromium, skip OS dependency installation, install the
|
|
ScreenCI skill, and install optional `playwright-cli` support.
|
|
|
|
Use this command in [Installation & First Video](/docs).
|
|
|
|
## `screenci test [playwrightArgs...]`
|
|
|
|
<!-- screenci-doc-video:docs/reference/cli -->
|
|
|
|
Run videos locally without the final recording pipeline:
|
|
|
|
<Tabs syncKey="package-manager">
|
|
<TabItem label="npm">
|
|
|
|
```bash
|
|
npx screenci test
|
|
npx screenci test videos/onboarding.video.ts
|
|
npx screenci test --grep "billing"
|
|
npx screenci test --ui
|
|
```
|
|
|
|
</TabItem>
|
|
<TabItem label="pnpm">
|
|
|
|
```bash
|
|
pnpm exec screenci test
|
|
pnpm exec screenci test videos/onboarding.video.ts
|
|
pnpm exec screenci test --grep "billing"
|
|
pnpm exec screenci test --ui
|
|
```
|
|
|
|
</TabItem>
|
|
<TabItem label="yarn">
|
|
|
|
```bash
|
|
yarn screenci test
|
|
yarn screenci test videos/onboarding.video.ts
|
|
yarn screenci test --grep "billing"
|
|
yarn screenci test --ui
|
|
```
|
|
|
|
</TabItem>
|
|
</Tabs>
|
|
|
|
Use this during normal authoring. Most trailing arguments are forwarded to
|
|
Playwright.
|
|
|
|
Common Playwright examples that also work here:
|
|
|
|
<Tabs syncKey="package-manager">
|
|
<TabItem label="npm">
|
|
|
|
```bash
|
|
npx screenci test --project=chromium
|
|
npx screenci test --grep "onboarding"
|
|
npx screenci test --ui
|
|
```
|
|
|
|
</TabItem>
|
|
<TabItem label="pnpm">
|
|
|
|
```bash
|
|
pnpm exec screenci test --project=chromium
|
|
pnpm exec screenci test --grep "onboarding"
|
|
pnpm exec screenci test --ui
|
|
```
|
|
|
|
</TabItem>
|
|
<TabItem label="yarn">
|
|
|
|
```bash
|
|
yarn screenci test --project=chromium
|
|
yarn screenci test --grep "onboarding"
|
|
yarn screenci test --ui
|
|
```
|
|
|
|
</TabItem>
|
|
</Tabs>
|
|
|
|
### `--mock-record`
|
|
|
|
<Tabs syncKey="package-manager">
|
|
<TabItem label="npm">
|
|
|
|
```bash
|
|
npx screenci test --mock-record
|
|
```
|
|
|
|
</TabItem>
|
|
<TabItem label="pnpm">
|
|
|
|
```bash
|
|
pnpm exec screenci test --mock-record
|
|
```
|
|
|
|
</TabItem>
|
|
<TabItem label="yarn">
|
|
|
|
```bash
|
|
yarn screenci test --mock-record
|
|
```
|
|
|
|
</TabItem>
|
|
</Tabs>
|
|
|
|
This keeps recording-like pacing enabled without starting the real recording
|
|
capture path. Use it when `test` passes but `record` exposes timing
|
|
differences.
|
|
|
|
If you want that behavior by default for a project, set
|
|
`test.mockRecord: true` in `screenci.config.ts`.
|
|
|
|
## `screenci record [playwrightArgs...]`
|
|
|
|
Record final output:
|
|
|
|
<Tabs syncKey="package-manager">
|
|
<TabItem label="npm">
|
|
|
|
```bash
|
|
npx screenci record
|
|
npx screenci record videos/onboarding.video.ts
|
|
npx screenci record --grep "billing"
|
|
npx screenci record --project=chromium
|
|
```
|
|
|
|
</TabItem>
|
|
<TabItem label="pnpm">
|
|
|
|
```bash
|
|
pnpm exec screenci record
|
|
pnpm exec screenci record videos/onboarding.video.ts
|
|
pnpm exec screenci record --grep "billing"
|
|
pnpm exec screenci record --project=chromium
|
|
```
|
|
|
|
</TabItem>
|
|
<TabItem label="yarn">
|
|
|
|
```bash
|
|
yarn screenci record
|
|
yarn screenci record videos/onboarding.video.ts
|
|
yarn screenci record --grep "billing"
|
|
yarn screenci record --project=chromium
|
|
```
|
|
|
|
</TabItem>
|
|
</Tabs>
|
|
|
|
`record` forwards normal Playwright file filters and `--grep`, so you can limit
|
|
recording to only some videos just like with `screenci test`.
|
|
|
|
Behavior:
|
|
|
|
- enables recording timing
|
|
- writes local output into `.screenci/`
|
|
- when `SCREENCI_SECRET` is missing, prints a blue one-time link and waits for browser sign-in before starting Playwright
|
|
- caches the pending auth session in `.screenci/link-session.json`, so rerunning `record` reuses the same link until it expires or completes
|
|
- uploads successful recordings when `SCREENCI_SECRET` is available
|
|
- prints a project URL after upload when rendering has been started remotely
|
|
|
|
Relevant options:
|
|
|
|
- `-c, --config <path>`
|
|
- `-v, --verbose`
|
|
|
|
Important restriction:
|
|
|
|
- `--retries` is not supported because ScreenCI forces retries to `0`
|
|
|
|
## `screenci info`
|
|
|
|
<Tabs syncKey="package-manager">
|
|
<TabItem label="npm">
|
|
|
|
```bash
|
|
npx screenci info
|
|
```
|
|
|
|
</TabItem>
|
|
<TabItem label="pnpm">
|
|
|
|
```bash
|
|
pnpm exec screenci info
|
|
```
|
|
|
|
</TabItem>
|
|
<TabItem label="yarn">
|
|
|
|
```bash
|
|
yarn screenci info
|
|
```
|
|
|
|
</TabItem>
|
|
</Tabs>
|
|
|
|
Prints remote project data for the current `projectName`, including video IDs
|
|
and whether public delivery is enabled.
|
|
|
|
Use this before public-delivery changes when you need the remote `videoId`:
|
|
|
|
```json
|
|
{
|
|
"projectName": "My Product",
|
|
"videos": [
|
|
{
|
|
"id": "video_123",
|
|
"name": "Onboarding",
|
|
"isPublic": true,
|
|
"language": "en",
|
|
"hasSubtitles": true
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
## `screenci make-public <videoId>`
|
|
|
|
<Tabs syncKey="package-manager">
|
|
<TabItem label="npm">
|
|
|
|
```bash
|
|
npx screenci make-public video_123
|
|
```
|
|
|
|
</TabItem>
|
|
<TabItem label="pnpm">
|
|
|
|
```bash
|
|
pnpm exec screenci make-public video_123
|
|
```
|
|
|
|
</TabItem>
|
|
<TabItem label="yarn">
|
|
|
|
```bash
|
|
yarn screenci make-public video_123
|
|
```
|
|
|
|
</TabItem>
|
|
</Tabs>
|
|
|
|
Enables public delivery for a video. Get the ID from `screenci info`.
|
|
|
|
When you make a video public, ScreenCI starts it in the same mode as the app:
|
|
|
|
- public delivery is enabled for the video
|
|
- auto-select latest is enabled
|
|
- the latest finished render for each language becomes the active public output
|
|
|
|
That means `make-public` is the CLI equivalent of turning on **Enable public
|
|
URL** in the dashboard.
|
|
|
|
## `screenci make-private <videoId>`
|
|
|
|
<Tabs syncKey="package-manager">
|
|
<TabItem label="npm">
|
|
|
|
```bash
|
|
npx screenci make-private video_123
|
|
```
|
|
|
|
</TabItem>
|
|
<TabItem label="pnpm">
|
|
|
|
```bash
|
|
pnpm exec screenci make-private video_123
|
|
```
|
|
|
|
</TabItem>
|
|
<TabItem label="yarn">
|
|
|
|
```bash
|
|
yarn screenci make-private video_123
|
|
```
|
|
|
|
</TabItem>
|
|
</Tabs>
|
|
|
|
Disables public delivery for a video.
|
|
|
|
This is the CLI equivalent of turning off **Enable public URL** in the
|
|
dashboard.
|
|
|
|
## What the CLI does not do
|
|
|
|
The CLI currently covers:
|
|
|
|
- project auth setup with `login`
|
|
- local iteration with `test`
|
|
- final capture and upload with `record`
|
|
- remote inspection with `info`
|
|
- public visibility changes with `make-public` and `make-private`
|
|
|
|
Manual version pinning is currently handled in the app UI:
|
|
|
|
- turn off **Auto-select latest version**
|
|
- open a language section
|
|
- choose the version to mark as **Selected**
|
|
|
|
## Shared environment and config behavior
|
|
|
|
These commands support `--config <path>`:
|
|
|
|
- `login`
|
|
- `test`
|
|
- `record`
|
|
- `info`
|
|
- `make-public`
|
|
- `make-private`
|
|
|
|
`SCREENCI_SECRET` is used for:
|
|
|
|
- login bootstrap and persistence
|
|
- uploads
|
|
- project info
|
|
- public delivery changes
|
|
|
|
If `envFile` is configured in `screenci.config.ts`, the CLI loads it
|
|
automatically. Otherwise it falls back to the project `.env`.
|
|
|
|
That env file is the recommended place to keep local ScreenCI secrets and other
|
|
runtime variables your setup needs. For example, if your local workflow depends
|
|
on an ElevenLabs BYOK key, keep `ELEVENLABS_API_KEY` there instead of hardcoding
|
|
it elsewhere. ScreenCI does not store raw API keys from that file.
|
|
|
|
## Related pages
|
|
|
|
- [Configuration](/docs/reference/configuration) for `screenci.config.ts`.
|