Instructions for using ovoBrowser CLI mode

The ovoBrowser CLI mode is used to launch desktop clients and local automation APIs in backend mode from the command line. It reuses the most recently logged in account session from the desktop secure storage, without requiring users to write their email, password, Refresh Token, or API Key into the command line.

1、 Applicable scenarios

• Start the ovoBrowser API using the startup script or local task scheduler;

• Run Playwright, Puppet, Selenium, or proprietary scripts without opening the main window;

• Fix API ports for local tools;

• Enable logged in accounts to provide environment, proxy, and browser lifecycle interfaces in the backend mode.

CLI mode is still a startup method for desktop clients, not an independent cloud service, nor does it bypass account permissions, team permissions, environment quotas, or local security boundaries.

2、 First use prerequisite

1. Open the ovoBrowser desktop client normally;

2. Login requires an account for automation;

3. Confirm that the client can enter the main interface normally;

4. Completely exit the client;

5. Use it again from the command line--cliStart up.

The account login credentials are saved in the secure storage of the operating system. CLI does not support or recommend using the following parameters:

--username
--password
--token
--api-key

If the login has expired, the account has been logged out, or the secure storage has been cleared, please log in again using the desktop interface.

3、 Find program path

If the default directory is used during installation, it can be copied from the 'Target' field of the desktop shortcutovoBrowser.exeThe complete path. Below is a placeholder path:

$OvoBrowserExe = "C:\Program Files\ovoBrowser\ovoBrowser.exe"

The actual path must be based on the current installation location of the computer.

4、 Start CLI mode

Use the last saved API port:

& $OvoBrowserExe --cli

Specify port:

& $OvoBrowserExe --cli --api-port 50325

You can also use equal sign writing:

& $OvoBrowserExe --cli --api-port=50325

The port must be an integer between 1-65535. Service only listens127.0.0.1Will not listen to local area network addresses or public network addresses.

After CLI startup:

• The main window is not displayed by default;

• The client is still running in the background and retains the tray entrance;

• The hidden rendering process will restore the account session in the secure storage;

• The API port will be launched and willenabled=trueSave the current port to the local configuration;

• The next time the desktop client starts normally, as long as it is still enabled last time, the port will be automatically restored.

5、 Output startup status

Output readable text:

& $OvoBrowserExe --cli --api-port 50325 --cli-print

Output single line JSON:

& $OvoBrowserExe --cli --api-port 50325 --cli-json

Example JSON field:

{
  "success": true,
  "mode": "cli",
  "running": true,
  "host": "127.0.0.1",
  "port": 50325,
  "url": "http://127.0.0.1:50325",
  "pid": 12345,
  "account": "stored-session"
}

Some Windows installation environments do not retain the standard output of GUI programs in the current terminal. Regardless of whether the terminal displays text, the service status should be confirmed through a health check.

6、 Confirm that the port and account session are available

First check the port:

$BaseUrl = "http://127.0.0.1:50325"
Invoke-RestMethod -Method Post -Uri "$BaseUrl/health" -ContentType "application/json" -Body "{}"

Successful response:

{
  "success": true,
  "data": {
    "running": true,
    "version": "0.4.3"
  }
}

Then check if the account session and workspace have been restored:

Invoke-RestMethod -Method Post -Uri "$BaseUrl/browser/list" -ContentType "application/json" -Body '{"page":0,"pageSize":1}'

/healthSuccess only indicates that the port has been listening;/browser/listSuccess indicates that the hidden client has restored the account session and can process account data. You can wait a few seconds before trying again at startup.

7、 Relationship with automatic startup after login

After the account is successfully restored through password login, registration, Google/GitHub login, invitation registration, or session saving, the local API will automatically start. The actual rules are as follows:

• After successful login, the API will be launched and savedenabled=trueAnd the current port;

• The client can restore the port in advance based on the saved state during the next startup, and will confirm again that the service is running after the account session is restored;

• Clicking 'Stop Service' on the 'API&MCP' page will immediately close the current port, but it will still automatically start the next successful login or session recovery;

• Use--cliIt will also explicitly boot the port and save it as enabled;

• After the client completely exits, the API process and port will be closed together.

8、 When there is already a client instance

OvoBrowser runs on a single instance. If the desktop client is already open, then execute:

& $OvoBrowserExe --cli --api-port 51234

The command will be handed over to the existing instance for processing, and the local API will be started or switched to the specified port, without starting the second set of account processes. After switching ports, the caller must updatebaseUrl.

9、 Stop CLI service

The CLI mode uses the same process as the desktop client. The following methods can be used to stop:

• Exit ovoBrowser from the system tray;

• Open the main window again and click "Stop Service" on the "API&MCP" page;

• Exit the ovoBrowser process normally.

Do not use forced process termination as a daily stopping method; Normal exit will close the browser kernel and local APIs, and complete necessary cleaning.

10、 Postman configuration

1. ImportovoBrowser-Local-API.postman_collection.json；

2. Open the collection Variables;

3. turnbaseUrlChange to the address used by CLI, for examplehttp://127.0.0.1:50325；

4. Run the 'health check' first;

5. Run the 'Environment List' again to confirm that the account session has been restored;

6. Call environment and proxy interfaces as needed.

Postman does not require Bearer Token, API Key, orx-api-keyThe local API only allows access to the current computer.

11、 Frequently Asked Questions

Connection refused

The CLI process is not running, the port is written incorrectly, the port is occupied, or the program fails to start. Check the command--api-portAnd confirm that the health check address is consistent.

The health check was successful, but the environment list indicates that the client is not ready

The hidden client is still restoring the login session. Please wait a few seconds and try again. If it continues to fail, open the desktop client normally, confirm that the account has not logged out and can enter the main interface.

The port is already occupied

Change to an unoccupied port, for example:

& $OvoBrowserExe --cli --api-port 51234

Login has expired

CLI does not accept account passwords. Please open the client normally and log in again. After logging out, run the CLI again.

The main window did not appear after executing the command

This is the expected behavior of CLI mode. You can open the main window from the tray or directly call the health check.

12、 Safety advice

• Only listen and call127.0.0.1；

• Do not expose local APIs to local or public networks through port mapping, reverse proxy, or tunneling;

• Do not disclose the proxy password Cookie、 Write the account password or complete API response to the public log;

• Do not save login passwords in command-line arguments, batch files, or task planners;

• Close the environment that is no longer in use after automation is completed;

• The team account only grants the script the permissions it truly needs.

13、 Parameter Quick Search

Related documents:

• API Document.md

• Code example for ovobrowser API call/hostman/ovoBrowser-Local-API.Postman_completion.json

• Code example for ovobrowser API call/README.md