CLI (openenv_cli)

The openenv CLI provides a set of commands for building, validating, and pushing environments to Hugging Face Spaces or a custom Docker registry. For an end-to-end tutorial on building environments with OpenEnv, see the building an environment guide.

openenv init

Initialize a new OpenEnv environment.

init(env_name, output_dir=None)

Initialize a new OpenEnv environment.

Creates a new directory with the environment name and generates all necessary files based on the OpenEnv template structure.

Example

$ openenv init my_game_env $ openenv init my_env --output-dir /path/to/projects

openenv build

Build Docker images for OpenEnv environments.

build(env_path=None, tag=None, context=None, dockerfile=None, no_cache=False, build_arg=None)

Build Docker images for OpenEnv environments.

This command builds Docker images using the environment's pyproject.toml and uv for dependency management. Run from the environment root directory.

Examples:

Build from environment root (recommended)

$ cd my_env $ openenv build

Build with custom tag

$ openenv build -t my-custom-tag

Build without cache

$ openenv build --no-cache

Build with custom build arguments

$ openenv build --build-arg VERSION=1.0 --build-arg ENV=prod

Build from different directory

$ openenv build src/envs/echo_env

openenv validate

OpenEnv validate command.

This module provides the 'openenv validate' command to check if environments are properly configured for multi-mode deployment.

validate(env_path=typer.Argument(None, help='Path to the environment directory (default: current directory)'), verbose=typer.Option(False, '--verbose', '-v', help='Show detailed information'))

Validate an environment for standardized structure and deployment readiness.

This command checks if an environment is properly configured with: - Required files (pyproject.toml, openenv.yaml, server/app.py, etc.) - Docker deployment support - uv run server capability - python -m module execution

Examples:

Validate current directory (recommended)

$ cd my_env $ openenv validate

Validate with detailed output

$ openenv validate --verbose

Validate specific environment

$ openenv validate src/envs/echo_env

openenv push

Push an OpenEnv environment to Hugging Face Spaces.

push(directory=None, repo_id=None, base_image=None, interface=None, no_interface=False, registry=None, private=False)

Push an OpenEnv environment to Hugging Face Spaces or a custom Docker registry.

This command: 1. Validates that the directory is an OpenEnv environment (openenv.yaml present) 2. Builds and pushes to Hugging Face Spaces or custom Docker registry 3. Optionally enables web interface for deployment

The web interface is enabled by default when pushing to HuggingFace Spaces, but disabled by default when pushing to a custom Docker registry.

Examples:

Push to HuggingFace Spaces from current directory (web interface enabled)

$ cd my_env $ openenv push

Push to HuggingFace without web interface

$ openenv push --no-interface

Push to Docker Hub

$ openenv push --registry docker.io/myuser

Push to GitHub Container Registry

$ openenv push --registry ghcr.io/myorg

Push to custom registry with web interface

$ openenv push --registry myregistry.io/path1/path2 --interface

Push to specific HuggingFace repo

$ openenv push --repo-id my-org/my-env

Push privately with custom base image

$ openenv push --private --base-image ghcr.io/meta-pytorch/openenv-base:latest

openenv serve

Serve OpenEnv environments locally (TO BE IMPLEMENTED).

serve(env_path=None, port=8000, host='0.0.0.0', reload=False)

Serve an OpenEnv environment locally.

TODO: This command is currently not implemented and has been deferred for later.

Planned functionality: - Run environment server locally without Docker - Support multiple deployment modes (local, notebook, cluster) - Auto-reload for development - Integration with environment's [project.scripts] entry point

For now, use Docker-based serving: 1. Build the environment: openenv build 2. Run the container: docker run -p 8000:8000

Or use uv directly

uv run --project . server --port 8000

API Reference

Entry point

OpenEnv CLI entry point.

This module provides the main entry point for the OpenEnv command-line interface, following the Hugging Face CLI pattern.

main()

Main entry point for the CLI.

CLI helpers

CLI utilities for OpenEnv command-line interface.

validate_env_structure(env_dir, strict=False)

Validate that the directory follows OpenEnv environment structure.

Parameters:

Name	Type	Description	Default
env_dir	Path	Path to environment directory	required
strict	bool	If True, enforce all optional requirements	False

Returns:

Type	Description
List[str]	List of validation warnings (empty if all checks pass)

Raises:

Type	Description
FileNotFoundError	If required files are missing

Validation utilities

Validation utilities for multi-mode deployment readiness.

This module provides functions to check if environments are properly configured for multi-mode deployment (Docker, direct Python, notebooks, clusters).

validate_multi_mode_deployment(env_path)

Validate that an environment is ready for multi-mode deployment.

Checks: 1. pyproject.toml exists 2. uv.lock exists and is up-to-date 3. pyproject.toml has [project.scripts] with server entry point 4. server/app.py has a main() function 5. Required dependencies are present

Returns:

Type	Description
tuple[bool, list[str]]	Tuple of (is_valid, list of issues found)

get_deployment_modes(env_path)

Check which deployment modes are supported by the environment.

Returns:

Type	Description
dict[str, bool]	Dictionary with deployment mode names and whether they're supported

format_validation_report(env_name, is_valid, issues)

Format a validation report for display.

Returns:

Type	Description
str	Formatted report string