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

# `snowglobe simulate`

> Launch a new simulation and start a Snowglobe session with your chatbot connected to that simulation.

*Available on versions 0.9.11+ of the client*

This command creates a new simulation and starts a Snowglobe session with your chatbot connected to it.  In this session your chatbot will only process scenarios from the newly launched simulation and no others.  Once the simulation is in a terminal state, your chatbot will disconnect from Snowglobe and the session will automatically close.

## Prerequisites

* Installed and authenticated `snowglobe`
* Wrapper created and tested
* `.snowglobe/agents.json` and `.snowglobe/config.rc` exist (created by `init`)
* A valid simulation config yaml file

## What this does

* Creates a new simulation using the values provided in the yaml config file
* Binds your wrapper so it can call Snowglobe during a session
* Processes scenarios created in the Snowglobe simulation and sends them to your chatbot
* Sends the chatbot's response back to Snowglobe
* Streams basic status to your terminal while active
* Exits once the simulation is in a terminal state

## Usage

```bash theme={null}
snowglobe simulate ./config.yml
```

## Simulation Configuration File

The config file supports two mutually exclusive shapes. Use the **generated** shape to let Snowglobe generate personas up to the bounds you set, or the **explicit personas** shape to run a fixed set of personas you describe yourself.

### Generated personas

```yaml theme={null}
version: int # Required, Currently only supports 1
max_personas: int # Required, Sets the upper bound for the number of personas to generate
max_conversations: int # Required, Sets the upper bound for the number of conversations to generate
max_conversation_length: int # Required, Sets the upper bound for the number of turns per conversation
agent_description: str # Optional, overrides the description set on the Agent during intial setup
simulation_prompt: str # Optional, provides coarse guidance for the  intent of the simulation
```

### Explicit personas

*Available on versions 1.0.0+ of the client*

Provide a list of persona descriptions instead of letting Snowglobe generate them. Each persona runs `conversations_per_persona` conversations.

```yaml theme={null}
version: int # Required, Currently only supports 1
personas: list[str] # Required, at least one persona description (e.g. "Alice, a friendly first-time user")
conversations_per_persona: int # Required, number of conversations to run per persona (>= 1)
max_conversation_length: int # Required, Sets the upper bound for the number of turns per conversation (>= 1)
```

#### Example

```yaml theme={null}
version: 1
personas:
  - "Alice, a friendly first-time user."
  - "Bob, a frustrated user who wants a refund."
conversations_per_persona: 3
max_conversation_length: 6
```

<Note>
  The `personas` and `max_personas` / `max_conversations` shapes can't be combined — provide one or the other. If `personas` is present, the explicit-personas shape is used.
</Note>

## CLI Options

All of the below options are required in order to successfully start a simulation.  If they are not provided in the command, and there are no reasonable defaults, you will be prompted to make selections using the CLI.

### `--agent-id`

The UUID for the Agent the simulation should target.

If you do not provide a value and you only have one agent configured, that agent will be automatically selected.
If you do not provide a value and you have more than one agent configued, you will be prompted to interactively select an agent.

### `--name`

A name for the simulation.

### `--agent-profile`

Skip auto-tuning and pin a specific Agent Profile by version number (e.g. '5') or UUID. The profile must already exist and be approved on the selected agent. Requires exactly one agent to be selected. Mutually exclusive with --no-agent-profile.

If you do not provide a value, do not specify --no-agent-profile, and you only have one agent profile available, that agent profile will be automatically selected.
If you do not provide a value, do not specify --no-agent-profile, and you have more than one agent profile available for the selected agent, you will be prompted to interactively select an agent profile.

### `--no-agent-profile`

Skip the Agent Profile (tuning) preflight and launch the simulation without an Agent Profile. Use this when the wrapper should never participate in the tool-mock tuning pipeline.

### `--organization-id`

The organization to create this simulation in. The specified org must have access to the agent.

If you do not provide a value and do not have `SNOWGLOBE_ORG_ID` specified either in `.snowglobe/config.rc` or via an environment variable, you will be prompted to interactively select an organization.  You can interactively configure a default organization beforehand with the `snowglobe select-organization` command.