# Google Studio Behind CLI

**Control Google AI Studio from your terminal or AI agent, using your normal Chrome or Edge browser.** Built by Behind Official.

This project provides the CLI, MCP server and agent skill. The companion browser extension lives in the separate **`google studio behind`** project. The agent can inspect AI Studio, enter prompts, operate visible controls, choose models and settings, upload context files, read responses and download media. A speech command automates single-speaker narration. Use Flow Behind for video, then attach Studio narration with FFmpeg.

This is an independent browser connector by Behind Official, not an official Google product. Browser automation uses your signed-in Google session; account requirements, available features, quotas and any provider charges remain Google's. It does not need your Google password or an API key for browser control.

## Current release

The npm package is `google-studio-behind-cli`. The companion browser extension is developed and packaged separately in `google studio behind`; it is not included in this CLI package. Generic controls support visible page workflows. A live Bengali speech workflow produced a verified 68.12-second WAV in the normal browser. Model selection has also been verified through browser controls; see [verification and limits](docs/verification.md). For audio, the reliable workflow is to let the agent click AI Studio's Download button and save through the browser. Automatic transfer into the CLI remains unreliable in live Studio.

The generic controls cover DOM-accessible workflows; this is not a claim that every AI Studio feature has been tested. Canvas-only editors, cross-origin iframes, controls requiring trusted native events, microphone/camera permissions, authentication and browser-native dialogs may need manual interaction. Direct media downloads must be accessible to the page; streaming-only media and cross-origin URLs without CORS support are not supported. See [verification and limits](docs/verification.md).

## Install

Requires Node.js 20+ and desktop Chrome or Edge. FFmpeg is optional, needed only to combine video and narration.

Install the CLI globally:

```sh
npm install -g google-studio-behind-cli
google-studio-behind --help
```

For local source development, clone the repository, then run `npm ci`, `npm run build` and `npm install -g .` from its folder. If a machine does not expose global executables on PATH, use `node bin/google-studio-behind.mjs` from the project.

### Connect your browser

1. Get the separate **`google studio behind`** folder or extract its connector ZIP. Register the folder containing `manifest.json` with `google-studio-behind extension-path "D:\FLOW CLI\google studio behind"` (use its actual location on your machine). Running `extension-path` without an argument then shows the registered path. You can also set `GOOGLE_STUDIO_BEHIND_EXTENSION` to override it.
2. Open `chrome://extensions` or `edge://extensions`, enable **Developer mode**, choose **Load unpacked**, and select that registered folder. Reload any existing AI Studio tab.
3. Run `google-studio-behind bridge start` in a terminal.
4. In another terminal run `google-studio-behind pair`. Paste its **local pairing token** and port into the extension popup and click **Save & connect**. This token is separate from any Google password or API key.
5. Open [AI Studio](https://aistudio.google.com/) in that browser and finish sign-in or verification yourself. Select the intended Studio tab if several are open. The connector opens a side panel for Home, Setup and Help; Setup has a copyable A to Z agent prompt. Connector release instructions live in the separate extension project.
6. Run `google-studio-behind doctor --json` and `google-studio-behind browser snapshot`.

Close the foreground bridge with Ctrl+C or run `google-studio-behind bridge stop`. `generate` and browser actions can also start the bridge automatically; `bridge stop` shuts down those processes too. Use one Studio bridge per state directory, and one paired connector at a time.

| Product | Default port | State directory |
| --- | --- | --- |
| Flow Behind | 8791 | `~/.flow-behind` |
| Google Studio Behind | **8792** | `~/.google-studio-behind` |

Both CLIs can run at the same time. Studio rejects port 8791 and does not use Flow's commands or state. To change Studio's port, use `--port 9002` or `GOOGLE_STUDIO_BEHIND_PORT=9002`, and enter the same port in the extension. For a separate independent Studio instance, also set `GOOGLE_STUDIO_BEHIND_HOME` to another directory.

## Control AI Studio

Take a snapshot first. It returns the page URL, visible text and controls with references such as `s1-e4`. References refer to that snapshot and become invalid after the next snapshot or navigation. **Use the references actually returned by your page**, not the example numbers below.

```sh
google-studio-behind browser snapshot
google-studio-behind browser act click --target s1-e4
google-studio-behind browser snapshot
google-studio-behind browser act fill --target s2-e7 --value "Write a short scene description."
google-studio-behind browser act click --target s2-e9
google-studio-behind browser snapshot
```

For a longer prompt, `--value-file prompt.txt` reads UTF-8 text without shell escaping. An exact `css:` selector is an alternative when you know the element; ambiguous selectors fail rather than selecting an arbitrary control.

| Action | Arguments | Behavior |
| --- | --- | --- |
| `snapshot` | none | Page text, controls, current values, links and media sources |
| `read` | `--target` | Read a specific response/control |
| `click` | `--target` | Buttons, tabs, checkboxes, visible menus |
| `fill` | `--target --value` or `--value-file` | Text inputs and editable content |
| `select` | `--target --value` | Exact native dropdown label/value |
| `press` | `--target --value Enter` | Dispatch a supported key event; verify the result |
| `scroll` | `--value 600`, optional `--target` | Scroll page or a panel in pixels |
| `navigate` | `--url` | Open a URL on `https://aistudio.google.com` |
| `upload` | `--target --file`, optional `--mime` | Attach one local file to a file input, up to 20 MB |
| `download` | `--target -o` | Save direct media, a link or a result Download button, up to 64 MB |
| `wait` | `--target css:… --timeout 60` | Wait for an observed selector to become visible |

For a custom model or voice dropdown, click it, take another snapshot, then click the observed option. The same controls support chat, image prompts, multi-speaker forms, model parameters, project navigation and other features exposed by your page. They do not assume a fixed model catalog. A click reports that it was dispatched; inspect a subsequent snapshot or downloaded output to verify the actual workflow result.

```sh
google-studio-behind browser act upload --target s3-e2 --file ./reference.png
google-studio-behind browser act download --target s4-e6 -o ./result.png
google-studio-behind browser act navigate --url https://aistudio.google.com/generate-speech
```

Browser commands return JSON and wait by default. Use `--no-wait` to obtain a job ID immediately. Use `--request-id` when retrying a request after an uncertain transport result. See [agent skill](skills/google-studio-behind/SKILL.md) for workflow guidance.

## Generate narration

Open the [speech page](https://aistudio.google.com/generate-speech), choose single-speaker mode, then:

```sh
google-studio-behind generate --text "Welcome to Behind." --wait --json
google-studio-behind generate --file narration.txt --style "Warm, clear and conversational" --output narration.wav --request-id scene-01 --wait --json
```

`--text`, `--file` and `--stdin` are mutually exclusive. Optional `--voice` and `--model` select exact visible option names; omit them to keep your current Studio choices. A requested option that cannot be located fails clearly. The dedicated shortcut supports one speaker; use browser controls for multi-speaker workflows.

The shortcut detects new audio rather than reusing an existing result. It saves WAV, MP3, OGG, FLAC or M4A according to the actual audio signature. If you specify an output extension, it must match the result. Omit `--output` to automatically choose the correct extension under the state directory. Existing files are never overwritten. No conversion occurs implicitly.

For the preferred workflow, let the agent generate the result, inspect the page, then click its observed Download button through the browser. The browser uses its normal Downloads folder or save dialog. Automatic transfer into the CLI can fail even when AI Studio generated audio; download the existing result instead of submitting another request.

The companion extension is packaged separately. Load the current `google studio behind` folder or its connector ZIP, and check `result.connector.version` in a browser snapshot to verify which code AI Studio loaded.

To save an already generated result without generating it again, take a snapshot and click its observed Download button in the browser:

```sh
google-studio-behind browser act click --target RESULT_DOWNLOAD_REF
```

Replace `RESULT_DOWNLOAD_REF` with the actual snapshot reference. Verify that the browser completed the download before reporting its path. Direct readable media transfer with `browser act download` is also available.

Speech has a default 600-second execution timeout, configurable with `--timeout 1..1800`. Waiting without a ready speech page may return a still-queued record; inspect `status` and the job ID instead of submitting another request. You can run browser navigation/diagnostics while speech is queued waiting for its page.

If the speech UI changes, use **Check page** in the extension. In **Advanced · page selectors**, configure exact CSS selectors for `text`, `style`, `submit`, `stop`, `voice`, `model`, `singleMode`, `audio`, `download` or `error`. Supply only needed overrides. The browser control commands remain available even when speech-specific controls cannot be resolved.

## Jobs and troubleshooting

```sh
google-studio-behind status --json
google-studio-behind doctor --json
google-studio-behind jobs list
google-studio-behind jobs get JOB_ID
google-studio-behind jobs wait JOB_ID --timeout 120
google-studio-behind jobs cancel JOB_ID
google-studio-behind queue pause
google-studio-behind queue resume
google-studio-behind logs
```

Jobs are persisted. Work is serialized; eligible queued actions run in order. Pausing prevents new dispatches and does not stop an active generation. Cancellation attempts the page's Stop control when this connector submitted the speech job; a generation already submitted to Google may continue. Restarting or disconnecting fails interrupted work rather than automatically charging for a second generation. Queued jobs survive restart. Inspect the page before explicitly retrying a failed job.

If Google displays an unknown/network/session error in an embedded browser, move to your normal Chrome or Edge with this extension installed. The connector cannot repair Google's session or account availability. For an unavailable control, inspect the latest snapshot instead of guessing selectors. Logs avoid prompt text, but local job history stores prompts and output paths; treat the state directory as private.

## Flow video + Studio audio

Generate/download your video with the existing `flow-behind` CLI on port 8791. Generate narration with Studio on 8792. Then:

```sh
google-studio-behind attach-audio --video flow-video.mp4 --audio narration.wav --output final-video.mp4 --shortest
```

FFmpeg must be on PATH, or set `FFMPEG_PATH` to its executable. Video is copied without re-encoding; narration is encoded to AAC. This replaces the video's audio track, does not automatically lip-sync, and refuses an existing output. `--shortest` ends the video at the shorter input's end; omit it to retain the longer duration.

## Agent skill and MCP

Install the bundled skill:

```sh
google-studio-behind skill-install
```

Default destination: `~/.codex/skills/google-studio-behind`. Use `--dir` for another agent's skill root, such as `~/.agents/skills`. Restart or refresh your agent's skill discovery if needed. Invoke it as **`$google-studio-behind`** when directing Studio work.

For any MCP client supporting stdio servers:

```json
{
  "mcpServers": {
    "google-studio-behind": {
      "command": "google-studio-behind-mcp",
      "env": { "GOOGLE_STUDIO_BEHIND_PORT": "8792" }
    },
    "flow-behind": { "command": "flow-behind-mcp" }
  }
}
```

If a client cannot resolve a global command, set `command` to the absolute Node executable and `args` to the absolute `bin/google-studio-behind-mcp.mjs` path. Windows launchers may also require this form.

Tools: `studio_browser`, `studio_generate_audio`, `studio_status`, `studio_list_jobs`, `studio_get_job`, `studio_cancel_job`, `studio_attach_audio`. Generation and browser tools return within about 20 seconds with a job record; poll `studio_get_job` if it remains queued/running. MCP uses stdout only for protocol messages.

## Development and packaging

```sh
npm ci
npm run check
npm pack
```

Build and test the extension from its own project:

```sh
cd "../google studio behind"
npm ci
npm run build
npx playwright install chromium
npm run test:browser
```

Browser tests live in that separate project and use a fresh profile and synthetic HTTPS page, with no request to Google. They use the sibling CLI project for bridge integration. `PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH` can select an existing compatible Chromium executable. Set `FFMPEG_PATH` to include video/audio composition in that test.

Track this CLI project's `src/`, `scripts/`, `test/`, `bin/`, lockfile, skill and documentation in Git. `bin/` contains handwritten entry points and belongs in source control. Generated `dist/`, test outputs, archives and dependencies are ignored by Git. The CLI npm archive includes compiled `dist/` so installed commands can run, and **does not include extension source or runtime files**. `npm pack` builds only the CLI and MCP server. The extension owns its source, build, browser tests and connector ZIP in the separate project. The CLI package is a private preview.

MIT licensed. See [architecture](docs/architecture.md) for the bridge protocol and security boundaries.