> ## Documentation Index
> Fetch the complete documentation index at: https://docs.screenforge.co/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI Reference

> Every director command, its flags, and what it does.

Install with `npm install -g @screenforge/director-cli`. Start with `director init` — the commands below are ordered the way you'll actually run them. Every command accepts `--api-url` (or `$DIRECTOR_API_URL`) to point at a non-default deployment; the default is `https://api.director.screenforge.co/api`.

## `director init`

Installs the Chromium browser Director drives. Run this first — every other command that touches a browser depends on it.

| Flag          | Description                                                                 |
| ------------- | --------------------------------------------------------------------------- |
| `--with-deps` | Also install OS-level libraries Chromium needs (Linux; may require `sudo`). |

## `director login`

Signs the CLI in to your Director account via a device-code browser handoff. Does **not** mint an API key by itself.

Writes `~/.director/credentials.json` (mode `0600`), scoped per `--api-url` — switching API URLs requires signing in again.

## `director mcp`

Wires Director's hosted MCP endpoint into a coding agent's config file.

| Flag              | Description                                                                                                                                                         |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--api-key <key>` | Required unless `--create-key` is used (or `$DIRECTOR_API_KEY`).                                                                                                    |
| `--create-key`    | Signs in if needed (reusing saved credentials), mints a fresh API key — the same kind you'd create from the dashboard's **API Keys** page — and prints it **once**. |
| `--agent <name>`  | Repeatable — target specific agent(s). Omit to auto-detect (Claude Code, Cursor, Claude Desktop, etc.).                                                             |
| `-g, --global`    | Write to the agent's global config instead of project-local.                                                                                                        |
| `-y, --yes`       | Skip confirmation prompts.                                                                                                                                          |

Fails with a clear error if no supported agent is detected — pass `--agent` explicitly in that case.

## `director session [code]`

The one command that opens a real browser on your machine. Captures a session from logging into your own product and uploads it to Director — used whenever an environment needs a fresh authenticated session, not just during setup.

| Flag                                 | Description                                                                                 |
| ------------------------------------ | ------------------------------------------------------------------------------------------- |
| `[code]` / `--code <code>`           | A pairing code (`DIR-XXXX-XXXX-XXXX`, 30 min expiry). The primary path — no API key needed. |
| `--api-key <key>`                    | Bearer key for the no-code/CI path (or `$DIRECTOR_API_KEY`).                                |
| `--environment <id>` / `-e`          | Record a session against an existing environment (used with `--api-key`).                   |
| `--name <name>` / `--base-url <url>` | Create a new environment inline instead of `--environment`.                                 |
| `--start-url <url>`                  | Page to open first (defaults to the environment's base URL).                                |
| `--timeout <minutes>`                | How long to leave the browser open waiting for you to press Enter. Default `10`.            |

Refuses to upload a session that has zero cookies and zero origins.

## `director doctor`

Read-only diagnostic — checks Node version, Chromium, saved account credentials, `$DIRECTOR_API_KEY`, and whether Director's API is reachable. Fixes nothing; exits non-zero if any check fails. Run this any time something isn't working.

## `director update`

Checks npm for a newer `@screenforge/director-cli` release and installs it globally if one exists. No flags.

<Note>
  Every command (except `update` itself) checks once a day whether a newer CLI version is available and prints a stderr nudge if so — silent under `$CI`, and never blocks or fails the command.
</Note>