> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/primeintellect-ai/verifiers/llms.txt
> Use this file to discover all available pages before exploring further.

# prime env init

> Create a new environment template

## Overview

The `prime env init` command scaffolds a new environment module with a basic template, including starter code, metadata, and documentation.

## Usage

```bash theme={null}
prime env init <env> [OPTIONS]
```

## Arguments

<ParamField path="env" type="string" required>
  Environment ID (will be normalized to use underscores for the package name).

  Example: `my-env` creates `environments/my_env/`
</ParamField>

## Options

<ParamField path="--path" type="string" default="./environments">
  Path to environments directory where the new environment will be created.
</ParamField>

<ParamField path="--rewrite-readme" type="flag">
  Overwrite README.md if it already exists.
</ParamField>

<ParamField path="--multi-file" type="flag">
  Create a multi-file package structure with `__init__.py` instead of a single-file module.
</ParamField>

<ParamField path="--openenv" type="flag">
  Initialize with the OpenEnv layout for tool-use environments. Creates `proj/` directory with OpenEnv project structure.
</ParamField>

## Created Structure

### Standard Environment

By default, creates a single-file module structure:

```
environments/my_env/
├── my_env.py           # Main implementation with load_environment()
├── pyproject.toml      # Dependencies and metadata
└── README.md           # Documentation template
```

### Multi-File Environment

With `--multi-file`, creates a package structure:

```
environments/my_env/
├── my_env/
│   ├── __init__.py     # Exports load_environment
│   └── my_env.py       # Main implementation
├── pyproject.toml
└── README.md
```

### OpenEnv Environment

With `--openenv`, creates an OpenEnv-based environment:

```
environments/my_env/
├── my_env.py           # Environment wrapper using vf.OpenEnvEnv
├── pyproject.toml      # With verifiers[openenv] dependency
├── README.md           # OpenEnv-specific documentation
└── proj/               # OpenEnv project directory
    ├── openenv.yaml    # OpenEnv manifest
    ├── pyproject.toml  # Project dependencies
    ├── server/
    │   ├── Dockerfile  # Container definition
    │   └── app.py      # FastAPI server
    └── README.md       # Project documentation
```

## Examples

### Create a Standard Environment

```bash theme={null}
prime env init my-env
```

**Output:**

```
Created environments/my_env/
  my_env.py
  pyproject.toml
  README.md
```

### Create a Multi-File Environment

```bash theme={null}
prime env init complex-env --multi-file
```

**Output:**

```
Created environments/complex_env/
  complex_env/__init__.py
  complex_env/complex_env.py
  pyproject.toml
  README.md
```

### Create an OpenEnv Environment

```bash theme={null}
prime env init tool-env --openenv
```

**Output:**

```
Created environments/tool_env/
  tool_env.py
  pyproject.toml
  README.md
  proj/openenv.yaml
  proj/pyproject.toml
  proj/server/Dockerfile
  proj/server/app.py
  proj/README.md
```

### Custom Path

```bash theme={null}
prime env init my-env --path ~/my-envs
```

Creates the environment in `~/my-envs/my_env/`.

## Template Contents

### Environment Implementation

The generated `my_env.py` contains a starter template:

```python theme={null}
import verifiers as vf

def load_environment(**kwargs) -> vf.Environment:
    """
    Loads a custom environment.
    """
    raise NotImplementedError("Implement your custom environment here.")
```

### pyproject.toml

Defines the package metadata and dependencies:

```toml theme={null}
[project]
name = "my-env"
description = "Your environment description here"
tags = ["placeholder-tag", "train", "eval"]
version = "0.1.0"
requires-python = ">=3.10"
dependencies = [
    "verifiers>=0.8.0",
]

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[tool.hatch.build]
include = ["my_env.py", "pyproject.toml"]

[tool.verifiers.eval]
num_examples = 5
rollouts_per_example = 3
```

### README.md

Provides a documentation template with sections for:

* Overview
* Datasets
* Task description
* Quickstart examples
* Environment arguments
* Metrics

## Next Steps

After creating an environment:

1. **Edit the environment code** in `my_env.py`
2. **Add dependencies** to `pyproject.toml` if needed
3. **Install the environment:**
   ```bash theme={null}
   prime env install my-env
   ```
4. **Test with an evaluation:**
   ```bash theme={null}
   prime eval run my-env -m gpt-4.1-mini -n 5
   ```

## OpenEnv Workflow

For OpenEnv environments, additional steps are required:

1. **Implement the OpenEnv server** in `proj/server/app.py`
2. **Build the Docker image:**
   ```bash theme={null}
   uv run vf-build my-env
   ```
3. **Install and test:**
   ```bash theme={null}
   prime env install my-env
   prime eval run my-env -m gpt-4.1-mini
   ```

See the [Environments documentation](https://docs.primeintellect.ai/environments) for detailed implementation guidance.

## Naming Conventions

* **Environment IDs** can use hyphens (e.g., `my-env`) or underscores (e.g., `my_env`)
* **Package names** normalize to underscores (e.g., `my_env`)
* **Directory names** match the package name (e.g., `environments/my_env/`)
* **Module names** match the package name (e.g., `my_env.py`)

## Troubleshooting

### Directory Already Exists

If the environment directory already exists, the command will skip creating existing files:

```
README.md already exists at environments/my_env/README.md, skipping...
```

Use `--rewrite-readme` to force overwrite the README.

### Invalid Environment Name

Environment names must be valid Python package names. Avoid special characters and spaces.