CLI Reference - Simplex

The simplex CLI is installed alongside the Python SDK and provides full access to the Simplex API from your terminal. All commands support --help for detailed usage information.

Auth

Authenticate with Simplex. Opens a browser-based OAuth flow by default.

# Browser-based login
simplex login

# Manual API key entry (for headless environments)
simplex login --api-key YOUR_API_KEY

Flag	Description
`--api-key KEY`	Skip the browser flow and authenticate with an API key directly

Credentials are saved to ~/.simplex/credentials.

`simplex whoami`

Display current authentication identity, including a masked API key and its source.

simplex whoami

Authenticated as: sk-...4f2a (source: environment variable)

`simplex logout`

Remove saved credentials from ~/.simplex/credentials.

simplex logout

Core

`simplex run`

Run a workflow and optionally wait for completion.

simplex run WORKFLOW_ID [--vars JSON] [--metadata STR] [--webhook-url URL] [--watch]

Argument / Flag	Description
`WORKFLOW_ID`	The workflow to run (required)
`--vars JSON`	Variables as a JSON string or path to a `.json` file
`--metadata`, `-m STR`	Metadata string to attach to the session
`--webhook-url URL`	Webhook URL for session completion notification
`--watch`, `-w`	Poll every 2s with a spinner until completion, then display outputs

Examples:

# Run with inline variables
simplex run wf_abc123 --vars '{"patient_id": "P-12345", "insurance_provider": "Aetna"}'

# Run with variables from a file
simplex run wf_abc123 --vars ./prior_auth_data.json --metadata "batch-2024-01"

# Run and wait for results
simplex run wf_abc123 --vars '{"policy_number": "POL-9876"}' --watch

When --watch is used, the CLI polls the session every 2 seconds and displays a spinner. On completion, it prints the session outputs, structured output, and file metadata.

`simplex editor`

Create a new workflow and start an interactive editor session.

simplex editor --name NAME --url URL [--vars JSON] [--prompt PROMPT] [--json]

Flag	Description
`--name`, `-n NAME`	Name for the new workflow (required)
`--url`, `-u URL`	Starting URL for the workflow (required)
`--vars JSON`	Initial variables as a JSON string or path to a `.json` file
`--prompt`, `-p PROMPT`	Initial prompt to send to the agent after the session starts
`--json`	Output machine-readable JSON

Returns: workflow_id, session_id, vnc_url, logs_url, message_url.

simplex editor --name "Aetna Prior Auth" --url "https://provider.aetna.com/auth"

# With an initial prompt — the agent starts working immediately
simplex editor --name "Insurance Form" --url "https://portal.example.com/intake" \
  --vars '{"name": "Jane Smith", "dob": "1985-03-15"}' \
  --prompt "Fill out the intake form using the provided data and submit it"

`simplex connect`

Stream live SSE events from a running session in the terminal.

simplex connect WORKFLOW_ID [--json]

Argument / Flag	Description
`WORKFLOW_ID`	A workflow ID or a full `logs_url`
`--json`	Output raw JSON events (useful for piping to other tools)

The CLI renders agent thinking, tool calls, pauses, completions, and errors in a formatted terminal display. When the agent triggers an AskUserQuestion event, the CLI prompts you for input interactively.

# Connect using a workflow ID
simplex connect wf_abc123

# Connect using a logs URL
simplex connect "https://api.simplex.sh/session/sess_xyz/logs"

# Pipe raw events to jq
simplex connect wf_abc123 --json | jq '.type'

`simplex send`

Send a message to a running session’s browser agent.

simplex send WORKFLOW_ID MESSAGE

Argument	Description
`WORKFLOW_ID`	The workflow whose active session should receive the message
`MESSAGE`	The message text to send

The CLI automatically resolves the active session’s message URL from the workflow ID.

simplex send wf_abc123 "Use the secondary insurance on file"

Session Control

`simplex pause`

Pause a running session. Looks up the active session from the workflow ID.

simplex pause WORKFLOW_ID

simplex pause wf_abc123

`simplex resume`

Resume a paused session.

simplex resume WORKFLOW_ID

simplex resume wf_abc123

`simplex interrupt`

Interrupt a running editor session’s agent mid-execution.

simplex interrupt WORKFLOW_ID

simplex interrupt wf_abc123

`simplex start-recording`

Start recording browser actions in a running editor session. Uses CDP to capture clicks, inputs, navigation, scroll events, and network activity.

simplex start-recording WORKFLOW_ID

simplex start-recording wf_abc123

`simplex stop-recording`

Stop recording and export captured actions as an agent-script directory. Returns action count, network event count, duration, and export path.

simplex stop-recording WORKFLOW_ID

simplex stop-recording wf_abc123

Workflow Management

`simplex workflows list`

List and search workflows. Displays a table with ID (truncated), Name, and Metadata.

simplex workflows list [--name STR] [--metadata STR]

Flag	Description
`--name`, `-n STR`	Filter by workflow name (partial match)
`--metadata`, `-m STR`	Filter by metadata string

# List all workflows
simplex workflows list

# Search by name
simplex workflows list --name "prior auth"

# Filter by metadata
simplex workflows list --metadata "production"

`simplex workflows vars`

Show the variable schema for a workflow. Displays a table with Name, Type, Required, Default, and Allowed Values. Also prints an example simplex run command with required variables pre-filled.

simplex workflows vars WORKFLOW_ID [--json]

Flag	Description
`--json`	Output raw JSON schema

simplex workflows vars wf_abc123

Variable Schema for "Aetna Prior Auth":

  Name                 Type    Required  Default  Allowed Values
  patient_id           string  Yes       -        -
  insurance_provider   enum    Yes       -        Aetna, Cigna, UHC
  is_urgent            bool    No        false    -

Example:
  simplex run wf_abc123 --vars '{"patient_id": "...", "insurance_provider": "..."}'

`simplex workflows set-vars`

Set the variable schema for a workflow. Fields can be specified inline or via a JSON file.

simplex workflows set-vars WORKFLOW_ID [--field SPEC]... [--file PATH] [--clear] [--json]

Flag	Description
`--field`, `-f SPEC`	Field specification (repeatable). See format below
`--file PATH`	Path to a JSON file containing the variable schema
`--clear`	Remove all existing variables before setting new ones
`--json`	Output result as JSON

Field format:

Format	Meaning
`name:type`	Optional field
`name!:type`	Required field
`name:enum:val1,val2`	Enum field with allowed values
`name!:type:description`	Required field with description

# Set variables inline
simplex workflows set-vars wf_abc123 \
  -f "patient_id!:string" \
  -f "insurance_provider!:enum:Aetna,Cigna,UHC" \
  -f "is_urgent:bool"

# Set variables from a JSON file
simplex workflows set-vars wf_abc123 --file ./vars_schema.json

# Clear and replace all variables
simplex workflows set-vars wf_abc123 --clear -f "policy_number!:string"

`simplex workflows outputs`

Show the structured output schema for a workflow. Displays Name, Type, and Description.

simplex workflows outputs WORKFLOW_ID [--json]

Flag	Description
`--json`	Output raw JSON schema

simplex workflows outputs wf_abc123

`simplex workflows set-outputs`

Set the structured output schema for a workflow.

simplex workflows set-outputs WORKFLOW_ID [--field SPEC]... [--file PATH] [--clear] [--json]

Flag	Description
`--field`, `-f SPEC`	Field specification (repeatable). See format below
`--file PATH`	Path to a JSON file containing the output schema
`--clear`	Remove all existing output fields before setting new ones
`--json`	Output result as JSON

Field format:

Format	Meaning
`name:type`	Output field
`name:type:description`	Output field with description
`name:enum:val1,val2`	Enum output field with allowed values

simplex workflows set-outputs wf_abc123 \
  -f "approval_status:enum:approved,denied,pending:Prior auth decision" \
  -f "reference_number:string:Auth reference number" \
  -f "expiration_date:string:Coverage expiration date"

`simplex workflows update`

Update a workflow’s metadata.

simplex workflows update WORKFLOW_ID --metadata STR

Flag	Description
`--metadata`, `-m STR`	New metadata string (required)

simplex workflows update wf_abc123 --metadata "production-v2"

Session Inspection

`simplex sessions status`

Get the status of a session. Shows whether the session is in progress, succeeded, is paused, and displays the final message, outputs, structured output, and file metadata.

simplex sessions status SESSION_ID [--watch]

Flag	Description
`--watch`, `-w`	Poll until the session completes

# Check status once
simplex sessions status sess_xyz789

# Watch until completion
simplex sessions status sess_xyz789 --watch

`simplex sessions events`

Poll events for a workflow’s active session. Shows agent text, tool calls, and errors.

simplex sessions events WORKFLOW_ID [--since INT] [--limit INT] [--json]

Flag	Description
`--since`, `-s INT`	Event index to start from (use `next_index` from previous call)
`--limit`, `-l INT`	Maximum number of events to return
`--json`	Output raw JSON events

# Get initial events
simplex sessions events wf_abc123

# Paginate from where you left off
simplex sessions events wf_abc123 --since 42 --limit 20

`simplex sessions logs`

Retrieve completed session logs as JSON. Returns an error if the session is still running.

simplex sessions logs SESSION_ID

simplex sessions logs sess_xyz789

`simplex sessions download`

Download files from a completed session. Downloads all files as a zip archive by default, or a specific file with --filename.

simplex sessions download SESSION_ID [--filename STR] [--output PATH]

Flag	Description
`--filename`, `-f STR`	Download a specific file by name instead of the zip archive
`--output`, `-o PATH`	Output path (defaults to current directory)

# Download all files as zip
simplex sessions download sess_xyz789

# Download a specific file
simplex sessions download sess_xyz789 --filename "prior_auth_confirmation.pdf"

# Save to a specific directory
simplex sessions download sess_xyz789 --output ./downloads/

`simplex sessions replay`

Download the session replay video as an MP4 file.

simplex sessions replay SESSION_ID [--output PATH]

Flag	Description
`--output`, `-o PATH`	Output path for the MP4 file (defaults to current directory)

simplex sessions replay sess_xyz789
simplex sessions replay sess_xyz789 --output ./replays/session.mp4

Practical examples

Run a prior authorization workflow end-to-end

# 1. Find the workflow
simplex workflows list --name "prior auth"

# 2. Check required variables
simplex workflows vars wf_abc123

# 3. Run with variables and watch
simplex run wf_abc123 \
  --vars '{"patient_id": "P-12345", "insurance_provider": "Aetna", "procedure_code": "27447"}' \
  --metadata "Dr. Smith - knee replacement" \
  --watch

# 4. Download the confirmation
simplex sessions download sess_xyz789 --filename "auth_confirmation.pdf"

Stream and interact with an editor session

# Start an editor session
simplex editor --name "Quote Builder" --url "https://portal.example.com/quotes"

# In another terminal, connect to watch the agent
simplex connect wf_abc123

# Send instructions to the agent
simplex send wf_abc123 "Select the commercial auto policy, not personal"

Batch process with a shell loop

for patient in P-001 P-002 P-003 P-004 P-005; do
  echo "Starting workflow for $patient..."
  simplex run wf_abc123 \
    --vars "{\"patient_id\": \"$patient\", \"insurance_provider\": \"Cigna\"}" \
    --metadata "$patient"
  sleep 2  # Rate limiting
done

​Auth

​simplex login

​simplex whoami

​simplex logout

​Core

​simplex run

​simplex editor

​simplex connect

​simplex send

​Session Control

​simplex pause

​simplex resume

​simplex interrupt

​simplex start-recording

​simplex stop-recording

​Workflow Management

​simplex workflows list

​simplex workflows vars

​simplex workflows set-vars

​simplex workflows outputs

​simplex workflows set-outputs

​simplex workflows update

​Session Inspection

​simplex sessions status

​simplex sessions events

​simplex sessions logs

​simplex sessions download

​simplex sessions replay

​Practical examples

​Run a prior authorization workflow end-to-end

​Stream and interact with an editor session

​Batch process with a shell loop