> ## Documentation Index
> Fetch the complete documentation index at: https://simplex.sh/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI Reference

> Complete reference for the Simplex command-line interface.

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

### `simplex login`

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

```bash theme={null}
# 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.

```bash theme={null}
simplex whoami
```

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

***

### `simplex logout`

Remove saved credentials from `~/.simplex/credentials`.

```bash theme={null}
simplex logout
```

***

## Core

### `simplex run`

Run a workflow and optionally wait for completion.

```bash theme={null}
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:**

```bash theme={null}
# 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.

```bash theme={null}
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`.

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
# 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.

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
simplex pause WORKFLOW_ID
```

```bash theme={null}
simplex pause wf_abc123
```

***

### `simplex resume`

Resume a paused session.

```bash theme={null}
simplex resume WORKFLOW_ID
```

```bash theme={null}
simplex resume wf_abc123
```

***

### `simplex interrupt`

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

```bash theme={null}
simplex interrupt WORKFLOW_ID
```

```bash theme={null}
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.

```bash theme={null}
simplex start-recording WORKFLOW_ID
```

```bash theme={null}
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.

```bash theme={null}
simplex stop-recording WORKFLOW_ID
```

```bash theme={null}
simplex stop-recording wf_abc123
```

***

## Workflow Management

### `simplex workflows list`

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

```bash theme={null}
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               |

```bash theme={null}
# 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.

```bash theme={null}
simplex workflows vars WORKFLOW_ID [--json]
```

| Flag     | Description            |
| -------- | ---------------------- |
| `--json` | Output raw JSON schema |

```bash theme={null}
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.

```bash theme={null}
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 |

```bash theme={null}
# 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.

```bash theme={null}
simplex workflows outputs WORKFLOW_ID [--json]
```

| Flag     | Description            |
| -------- | ---------------------- |
| `--json` | Output raw JSON schema |

```bash theme={null}
simplex workflows outputs wf_abc123
```

***

### `simplex workflows set-outputs`

Set the structured output schema for a workflow.

```bash theme={null}
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 |

```bash theme={null}
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.

```bash theme={null}
simplex workflows update WORKFLOW_ID --metadata STR
```

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

```bash theme={null}
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.

```bash theme={null}
simplex sessions status SESSION_ID [--watch]
```

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

```bash theme={null}
# 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.

```bash theme={null}
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                                          |

```bash theme={null}
# 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.

```bash theme={null}
simplex sessions logs SESSION_ID
```

```bash theme={null}
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`.

```bash theme={null}
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)                 |

```bash theme={null}
# 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.

```bash theme={null}
simplex sessions replay SESSION_ID [--output PATH]
```

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

```bash theme={null}
simplex sessions replay sess_xyz789
simplex sessions replay sess_xyz789 --output ./replays/session.mp4
```

***

## Practical examples

### Run a prior authorization workflow end-to-end

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
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
```