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. 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.

Related MCP server: Cloudflare Playwright MCP

Install

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

Install the CLI globally:

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 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.

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.

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.

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.

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 for workflow guidance.

Generate narration

Open the speech page, choose single-speaker mode, then:

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:

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

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:

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:

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:

{
  "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

npm ci
npm run check
npm pack

Build and test the extension from its own project:

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 for the bridge protocol and security boundaries.