Advanced — CLI and API

This is the developer and CI/CD automation companion to AI Studio Quick start. It covers running AI Studio's autonomous agent from a terminal or build pipeline using robonito-cli, and driving it programmatically via the backend API.

The CLI (`robonito-cli`)

The Robonito CLI runs the same autonomous web-testing agent as the desktop application directly from your command line or continuous integration (CI) container. CLI v1 supports the Web platform.

Prerequisites

Node.js 20 or newer.
An active Robonito account with access to at least one organization and workspace.
Chromium installed (via Playwright or system browser).
(Optional) A local Ollama instance if you are running private on-premise models.

Installation

Install the CLI globally using npm:

npm install -g robonito-cli

Or execute it directly via npx:

npx robonito-cli --help

Authentication & Setup

Before running tests, authenticate the CLI with your Robonito account:

robonito-cli auth login

This opens your default browser for single-sign-on verification. On success, the CLI:

Stores the secure session token in your operating system's credential vault.
Prompts you to select your default Organization and Workspace.
Configures your default AI provider and model preferences.

For headless CI/CD environments (GitHub Actions, GitLab CI, Jenkins), you can bypass the interactive browser login by setting the ROBONITO_AUTH_TOKEN environment variable in your pipeline secrets.

Common CLI Commands

# Interactive terminal session
robonito-cli

# Execute a one-shot goal and exit
robonito-cli run "Test login on https://www.saucedemo.com with standard_user"

# Run in Plan Mode (generates and prints plan before acting)
robonito-cli run "Plan coverage for https://example.com" --planning

# Run in Explore Mode (autonomously walks and saves key user flows)
robonito-cli run "Explore https://example.com and discover critical flows" --explore

# Attach requirements or test data files
robonito-cli run "Verify user checkout against these rules" --attach ./test-specs.md

# Adopt a specific testing persona
robonito-cli run "Verify dashboard as clinical staff" --persona clinician -w <workspaceId>

Command Options Reference

Option	Purpose	Default
`-i, --instructions <string>`	Direct prompt instructions (`-` reads from standard input).	Interactive prompt.
`--attach <path>`	Attach a file for agent context (repeatable).	None.
`-p, --provider <type>`	AI provider: `robonito`, `anthropic`, `openai`, `google`, `ollama`.	`robonito`.
`-m, --model <id>`	Specific model ID to use.	Provider default.
`--planning`	Enable Plan Mode (review strategic plan before browser actions).	Off.
`--explore`	Enable Explore Mode (autonomous flow mapping and test generation).	Off.
`-w, --workspace-id <id>`	Target workspace ID where test cases will be saved.	Active workspace.
`-t, --thread-id <id>`	Resume a specific existing chat thread.	New thread.
`--headed`	Launch visible browser window (useful for local debugging).	Headless in CI.
`--non-interactive`	Disable Human-in-the-Loop prompts for unattended automation.	Interactive.
`--hitl-timeout-ms <ms>`	Maximum milliseconds to wait for human intervention before failing.	`600000` (10 min).
`--output <format>`	Output format: `human` (formatted terminal text) or `jsonl`.	`human`.
`--json-summary <path>`	Write execution summary to a JSON file.	None.
`--evidence <path>`	Save a redacted ZIP evidence bundle containing screenshots and trace logs.	None.

Credential Security:

Never commit API keys or auth tokens to source control. In CI/CD pipelines, inject ROBONITO_AUTH_TOKEN as a masked pipeline secret.

Environment Variables

Variable	Default	Purpose
`ROBONITO_AUTH_TOKEN`	None	Access token for unattended CI/CD automation.
`ROBONITO_SERVER_URL`	Cloud Default	Robonito API server endpoint.
`ROBONITO_WORKSPACE_ID`	None	Default workspace ID override.
`ROBONITO_ORGANIZATION_ID`	None	Default organization ID override.
`OLLAMA_BASE_URL`	`http://localhost:11434`	Endpoint for local Ollama instances.

Exit Codes for CI/CD

Exit Code	Meaning	CI Action
`0`	Success: Test goals reached, assertions passed, tests saved.	Pass build.
`1`	Configuration error, invalid arguments, or missing server connection.	Fail build.
`2`	Test execution failure: Application defect or failed assertion.	Fail build (log bug).
`3`	Authentication failure: Expired or invalid token.	Fail build (check secret).
`4`	Human intervention required, but running in non-interactive mode.	Fail build.
`5`	Token budget or step execution limit exhausted.	Review prompt budget.
`130`	Interrupted (`Ctrl+C` or SIGINT).	Cancelled build.

App-Server API

For deep integration with custom test harnesses, developer portals, or internal tooling, Robonito exposes a REST API at /ai-studio:

HTTP Method & Path	Description
`POST /ai-studio/threads`	Create a new AI Studio conversation thread.
`GET /ai-studio/threads`	List all existing threads for the workspace.
`POST /ai-studio/threads/:id/messages`	Dispatch a prompt to start an autonomous run.
`GET /ai-studio/threads/:id/messages`	Retrieve conversation stream, step history, and tool outputs.
`PATCH /ai-studio/threads/:id/bind-suite`	Bind a thread to its target destination suite.
`POST /ai-studio/test-cases/enqueue`	Enqueue a generated test case for asynchronous persistence.
`GET /ai-studio/test-cases/persistence/:jobId`	Poll persistence status for a saved test case.

AI Studio Quick Start — Getting started in the desktop app.
Choose an Agent Mode — Detailed guide to Default, Plan, and Explore modes.
Agentic Testing — Benchmarking and evaluating autonomous agents.

Reference

Agentic Testing