Simplex Python SDK & CLI

Official Python SDK and CLI for the Simplex browser automation platform.

Installation

pip install simplex

This installs both the Python SDK (from simplex import SimplexClient) and the CLI (simplex command).

Authentication

# Option 1: Environment variable
export SIMPLEX_API_KEY="your-api-key"

# Option 2: Login command (saves to ~/.simplex/credentials)
simplex login

Claude Code Plugin

Give Claude Code full knowledge of the Simplex CLI and SDK:

/plugin install simplexlabs/simplex-python

Once installed, Claude Code automatically knows how to use simplex editor, simplex connect, simplex run, and the full Python SDK.

CLI

`simplex editor` — Create a workflow and start an interactive session

simplex editor --name "My Workflow" --url "https://example.com"
simplex editor -n "My Workflow" -u "https://example.com" --var key=value
simplex editor -n "Test" -u "https://example.com" --json

Creates a workflow, starts a browser session, and streams live agent events. Prints session info (session_id, workflow_id, vnc_url) then streams SSE events until Ctrl+C.

`simplex connect` — Stream events from a running session

simplex connect <session_id>
simplex connect "https://host:port/stream" --json

`simplex run` — Run an existing workflow

simplex run <workflow_id>
simplex run <workflow_id> --var email=test@test.com --watch

`simplex send` — Send a message to a running session

simplex send <session_id> "Click the login button"

`simplex pause` / `simplex resume`

simplex pause <session_id>
simplex resume <session_id>

`simplex workflows list`

simplex workflows list --name "search term"

`simplex sessions`

simplex sessions status <session_id>
simplex sessions logs <session_id>
simplex sessions download <session_id> --filename report.pdf --output ./report.pdf
simplex sessions replay <session_id> --output replay.mp4

`simplex login` / `whoami` / `logout`

simplex login       # Prompts for API key
simplex whoami      # Shows current auth status
simplex logout      # Removes saved credentials

Python SDK

Quick Start

from simplex import SimplexClient

client = SimplexClient(api_key="your-api-key")

# Start an interactive editor session
result = client.start_editor_session(
    name="My Session",
    url="https://example.com",
    test_data={"username": "test"},
)
print(f"Session: {result['session_id']}")
print(f"VNC: {result['vnc_url']}")

# Stream live events
for event in client.stream_session(result["logs_url"]):
    print(event)

# Send a message to the agent
client.send_message(result["message_url"], "Click the login button")

# Close the session
client.close_session(result["session_id"])

Client

client = SimplexClient(
    api_key="your-api-key",
    base_url="https://api.simplex.sh",  # Optional
    timeout=30,                          # Request timeout in seconds
    max_retries=3,                       # Retry attempts
    retry_delay=1.0,                     # Delay between retries
)

Workflow Management

# Create
result = client.create_workflow(name="My Workflow", url="https://example.com")
workflow_id = result["workflow"]["id"]

# Get
workflow = client.get_workflow(workflow_id)

# Update
client.update_workflow(workflow_id, name="New Name", url="https://new-url.com")

# Search
results = client.search_workflows(workflow_name="search term")

Editor Sessions

# Start an editor session (creates workflow + browser session)
# NOTE: Takes 10-15 seconds. Use timeout=120.
result = client.start_editor_session(
    name="My Session",
    url="https://example.com",
    test_data={"username": "test"},
)
# Returns: succeeded, workflow_id, session_id, vnc_url, logs_url, message_url, filesystem_url

# Stream live SSE events
for event in client.stream_session(result["logs_url"]):
    event_type = event.get("event") or event.get("type", "")
    print(f"[{event_type}] {event}")

# Send a message to the agent
client.send_message(result["message_url"], "Click the login button")

Run Workflows

import time

result = client.run_workflow("workflow-id", variables={"key": "value"})

# Poll for completion
while True:
    status = client.get_session_status(result["session_id"])
    if not status["in_progress"]:
        break
    time.sleep(2)

if status["success"]:
    print(status["scraper_outputs"])
    print(status["structured_output"])

Session Management

client.pause(session_id)
client.resume(session_id)
client.close_session(session_id)
client.get_session_status(session_id)
client.retrieve_session_logs(session_id)
client.download_session_files(session_id)
client.retrieve_session_replay(session_id)

SSE Event Format

Events from stream_session() are dicts. The event type is in the event key:

Event	Description
`RunContent`	Agent text output
`ToolCallStarted`	Tool invocation started
`ToolCallCompleted`	Tool result
`FlowPaused`	Session paused
`FlowResumed`	Session resumed
`RunCompleted`	Agent finished
`RunError`	Error occurred

Error Handling

from simplex import (
    SimplexError,
    AuthenticationError,
    RateLimitError,
    NetworkError,
    ValidationError,
    WorkflowError,
)

try:
    result = client.run_workflow("workflow-id")
except AuthenticationError:
    print("Invalid API key")
except RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after}s")
except WorkflowError as e:
    print(f"Workflow error: {e.message}, session: {e.session_id}")
except SimplexError as e:
    print(f"Error: {e.message}")

Requirements

Python 3.9+
requests>=2.25.0

License

MIT License - see LICENSE for details.

Release files for simplex 3.1.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for simplex 3.1.1
File	Size	Uploaded
simplex-3.1.1.tar.gz	38.5 kB	Apr 27, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for simplex 3.1.1
File	Interpreter	ABI	Platform	Reset
simplex-3.1.1-py3-none-any.whl 44.0 kB Apr 27, 2026	Python 3	none	any	Details

Total release size:82.5 kB

Release files / simplex-3.1.1.tar.gz

Download URL	simplex-3.1.1.tar.gz
Size	38.5 kB
Tags	Source
SHA-256 checksum How to use checksums	`9d8bf483ae8a6e0cf89e602fc4b74aceb843b4db6a073ea08cc31b082bcda9d2`
BLAKE2b-256 checksum How to use checksums	`3bec75ab9146516e56133a2157b59c5905b01aa1d6d2ddf9ec1e3656e2c78d32`
Upload date	Apr 27, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.12.11`

Release files / simplex-3.1.1-py3-none-any.whl

Download URL	simplex-3.1.1-py3-none-any.whl
Size	44.0 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`c020e1934e5f938132c7ce770a2a61d78d5716cf52270048d0e0c3e68e5d82f1`
BLAKE2b-256 checksum How to use checksums	`8f671f9cbef99b33ea8b7e88be063770cd912a3041854da02175243091a7800c`
Upload date	Apr 27, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.12.11`