CLI Mode

CLI (Command Line Interface) mode starts Virtual Browser’s local API service from the terminal so scripts, CI/CD, or other tools can call it unattended and read the port and api-key.

Pro feature

CLI mode, like the REST API, is Pro only. Sign in with an active membership before starting, or pass a token on the command line.

When to use it

• Batch automation against Virtual Browser API
• CI/CD or scheduled jobs
• Run as a local service for other systems
• Quickly check whether the API service is up

Prerequisites

1. Virtual Browser installed (Windows or macOS)
2. Active Pro membership
3. Sign in once in the GUI, or pass credentials/token at startup

Quick start

Start CLI service (background by default)

Windows:

VirtualBrowser.exe --cli

macOS:

"/Applications/Virtual Browser.app/Contents/MacOS/Virtual Browser" --cli

--cli runs in the background by default. Use --cli-print to read port and api-key.

Foreground (debugging)

VirtualBrowser.exe --cli --cli-foreground

Foreground mode keeps the terminal attached for logs.

JSON output

VirtualBrowser.exe --cli --cli-json
VirtualBrowser.exe --cli-print --cli-json

For automation, prefer --cli-json to parse port, apiKey, alive, etc.

Login with account or token

# Username / password
VirtualBrowser.exe --cli --username=YOUR_USERNAME --password=YOUR_PASSWORD

# Short flags
VirtualBrowser.exe --cli -u YOUR_USERNAME -p YOUR_PASSWORD

# Token
VirtualBrowser.exe --cli --token=YOUR_TOKEN
VirtualBrowser.exe --cli --x-token=YOUR_TOKEN

Check status

VirtualBrowser.exe --cli-print
VirtualBrowser.exe --cli-print --cli-json

Flags

Flag	Description
--cli	Start CLI API service (background default)
--cli-foreground / --foreground	Foreground; blocks terminal
--cli-print	Print current CLI instance info
--cli-json	JSON output
--username=... / -u ...	Username
--password=... / -p ...	Password
--token=... / --x-token=...	Auth token
--cli-silent / --silent / -q	Quiet output
--cli-verbose / -v	Verbose output
--help / -h	Help

FAQ

“Membership required”

CLI is Pro-only. Sign in as a member in the GUI, or pass --username/--password or --token.

“Another instance is running”

Virtual Browser is single-instance. Close the GUI or other CLI first, or use --cli-print to inspect the running instance.

How to confirm success?

Run --cli-print --cli-json and check port, apiKey, and alive: true. Then call http://localhost:{port} with your api-key.

Related

• Automation API
• API overview
• Plans & features