Skip to main content

​
Overview

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

​
Usage

prime env init <env> [OPTIONS]

​
Arguments

​
env
string
required
Environment ID (will be normalized to use underscores for the package name).Example: my-env creates environments/my_env/

​
Options

​
--path
string
default:"./environments"
Path to environments directory where the new environment will be created.
​
--rewrite-readme
flag
Overwrite README.md if it already exists.
​
--multi-file
flag
Create a multi-file package structure with __init__.py instead of a single-file module.
​
--openenv
flag
Initialize with the OpenEnv layout for tool-use environments. Creates proj/ directory with OpenEnv project structure.

​
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

prime env init my-env
Output: 
Created environments/my_env/
  my_env.py
  pyproject.toml
  README.md

​
Create a Multi-File Environment

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

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

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: 
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: 
[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: 
    prime env install my-env
  4. Test with an evaluation: 
    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: 
    uv run vf-build my-env
  3. Install and test: 
    prime env install my-env
prime eval run my-env -m gpt-4.1-mini
See the Environments documentation 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.

Build docs developers (and LLMs) love

Get started for freeTalk to us