Director CLI

Screenforge Director is the demo agent — give it a URL and one sentence, and it operates your product in a real browser, records everything, and renders a polished demo video. This CLI is the command-line half of that.

• director mcp — connect Director's MCP server to your coding agent (Claude Code, Cursor, Claude Desktop, ...), so it can trigger and check on demos for you. Start here — this is how Director is normally used, an agent driving it on your behalf rather than you calling the API by hand.
• director session — a supporting command for the one case mcp alone can't cover: a product that sits behind a login. Capture a browser session so Director can demo it without ever receiving your password. (Not called login: this never logs in to Director — you log into your own product, and this captures the resulting session.)
• director init — installs the one prerequisite director session needs (Playwright's Chromium). Run this once, right after installing the CLI.
• director login — sign in to your Director account from this machine. Only needed if you use director mcp --create-key; mcp will trigger this automatically if you haven't run it yet.
• director doctor — checks Node, Chromium, sign-in state, and API reachability, and reports what's wrong. Read-only; fixes nothing itself.
• director update — updates the CLI to the latest published version. Every command also checks in the background (at most once a day) and prints a one-line reminder here when a newer version is out.

Install

curl -fsSL https://director.screenforge.co/cli/install.sh | sh
director init

or, if you'd rather not run a global install: npx @screenforge/director-cli <command> works for any command below without installing anything (npx @screenforge/director-cli init still needs to run once before session).

director mcp

Wire Director's MCP server into your coding agent (Claude Code, Cursor, Claude Desktop, and others) with one command instead of hand-editing config files:

director mcp --api-key dir_...

Detects supported agents in the current project and configures each; pass --agent <name> (repeatable) to target one explicitly, --global to install to the agent's global config instead of the current project, and -y to skip confirmation prompts.

Don't have an API key yet? Skip the dashboard entirely:

director mcp --create-key

This signs you in (opens a browser to approve — the same flow as director login — only if you aren't already signed in), creates a fresh API key, and wires it up in one step. Re-running it later reuses your saved sign-in instead of opening a browser again, as long as it's still valid.

| Flag | Meaning | |---|---| | --api-key <key> | API key (or $DIRECTOR_API_KEY) | | --create-key | No key yet? Sign in (opens a browser if needed) and create one automatically | | --api-url <url> | Director API (or $DIRECTOR_API_URL) | | --agent <name> | Target a specific agent (repeatable) — omit to auto-detect | | -g, --global | Install to the global config instead of the current project | | -y, --yes | Skip confirmation prompts |

director session

Capture a browser session so Screenforge Director can record demos of a product that sits behind a login — without ever receiving your password. (Not called login: it never authenticates anything with Director — you log into your own product, and this captures the resulting session.)

director session DIR-XXXX-XXXX-XXXX

Ask whoever set up the demo for a login code. It is single-use and expires after 30 minutes.

What happens

1. A browser window opens on your product.
2. You sign in exactly as you normally would — Google SSO, Okta, a 2FA push, a magic link. Anything that ends with you logged in works.
3. You press Enter in the terminal.
4. The resulting session (cookies, localStorage, IndexedDB) is uploaded.

What is uploaded is the session, not your credentials. Director replays it in its own browser to reach pages that need a login, which is why it can demo flows no automated form-fill could ever get through.

The session is encrypted at rest and never readable through the API — not even by the account that owns it.

CI, or no human present

DIRECTOR_API_KEY=dir_… director session \
  --environment env_abc123 \
  --api-url https://api.director.screenforge.co/api

Already have Playwright storage state in your test suite? Skip this tool and POST it directly — see the Director docs for the five-line snippet.

Options

| Flag | Meaning | |---|---| | --api-url <url> | Director API (or $DIRECTOR_API_URL) | | --start-url <url> | Page to open for logging in (default: the environment's base URL) | | --timeout <minutes> | How long to leave the browser open (default 10) | | --environment <id> | CI form: environment to attach to (needs --api-key) | | --api-key <key> | CI form (or $DIRECTOR_API_KEY); not needed with a code |

Known limitation: passkeys

Passkeys are bound to both the origin and the device, so a passkey login captured on your machine cannot authenticate from Director's workers. Use a password or SSO account for demo purposes.

director init

Installs Playwright's Chromium — the one thing director session needs that isn't in the npm package (Playwright ships browsers as a separate on-demand download). Run this once, right after installing the CLI:

director init

If Chromium fails to launch afterwards, it's almost always a missing OS library on Linux — re-run with --with-deps (may need sudo):

director init --with-deps

| Flag | Meaning | |---|---| | --with-deps | Also install the OS-level libraries Chromium needs (Linux only; may require sudo) |

director login

Signs the CLI in to your Director account:

director login

Opens a browser to approve the sign-in (via the same magic-link flow as the dashboard), then saves the result to ~/.director/credentials.json.

This does not create an API key by itself — that's what director mcp --create-key is for. login only exists for the case where you want to sign in ahead of time; day to day, mcp --create-key triggers this automatically the first time it needs to.

| Flag | Meaning | |---|---| | --api-url <url> | Director API (or $DIRECTOR_API_URL) |

director doctor

Checks whether this machine is set up for director — one command instead of guessing which of five things is broken:

director doctor

Director CLI doctor

  ✔ Node.js: v22.4.0
  ✔ Playwright Chromium: installed and launches
  – Director account: not signed in — run `director login`, or pass --api-key to `director mcp`
  – DIRECTOR_API_KEY: not set — `director mcp` needs --api-key, --create-key, or this
  ✔ Director API (https://api.director.screenforge.co/api): reachable (version 1.4.0)

3 ok, 2 warning(s), 0 failure(s)

Read-only — it reports what it found and exits non-zero if anything failed, but never installs or signs in for you. director init and director login do the actual fixing.

| Flag | Meaning | |---|---| | --api-url <url> | Director API (or $DIRECTOR_API_URL) |

director update

Updates the CLI to the latest version published on npm:

director update

Checks the npm registry, and if a newer version exists, runs npm install -g @screenforge/director-cli@latest to fetch it. Prints "Already up to date" and does nothing if you're already on the latest.

You don't have to run this proactively: every other command checks the registry in the background (throttled to once a day, cached under ~/.director/) and prints a one-line reminder pointing here when a newer version is available. Skipped entirely under CI ($CI set).