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.

openenv.cli.commands.init.init(env_name: str, output_dir: str | None = None) → 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.

openenv.cli.commands.build.build(env_path: str | None = None, tag: str | None = None, context: str | None = None, dockerfile: str | None = None, no_cache: bool = False, build_arg: list[str] | None = None) → 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 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.

openenv.cli.commands.validate.validate(target: str | None = None, url: str | None = None, json_output: bool = False, timeout: float = 5.0, verbose: bool = False) → None

Validate local environments and running OpenEnv servers.

Local validation 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

Runtime validation checks if a live OpenEnv server conforms to the versioned runtime API contract and returns a criteria-based JSON report.

Examples:

# Validate current directory (recommended) $ cd my_env $ openenv validate

# Validate a running environment and return JSON criteria $ openenv validate –url http://localhost:8000 $ openenv validate https://my-env.hf.space

# Validate with detailed output $ openenv validate –verbose

# Validate specific environment $ openenv validate envs/echo_env

openenv push

Push an OpenEnv environment to Hugging Face Spaces.

openenv.cli.commands.push.push(directory: str | None = None, repo_id: str | None = None, base_image: str | None = None, interface: bool = None, no_interface: bool = False, registry: str | None = None, private: bool = False, create_pr: bool = False, exclude: str | None = None) → None

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 repo and open a Pull Request $ openenv push my-org/my-env –create-pr $ openenv push –repo-id my-org/my-env –create-pr

# 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).

openenv.cli.commands.serve.serve(env_path: str | None = None, port: int = 8000, host: str = '0.0.0.0', reload: bool = False) → None

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 <image-name>

Or use uv directly:

uv run –project . server –port 8000

openenv fork

Fork (duplicate) a Hugging Face Space using the Hub API.

openenv.cli.commands.fork.fork(source_space: str, repo_id: str | None = None, private: bool = False, set_env: list[str] = [], set_secret: list[str] = [], hardware: str | None = None) → None

Fork (duplicate) a Hugging Face Space to your account using the Hub API.

Uses the Hugging Face duplicate_space API. You can set environment variables and secrets, and request hardware/storage/sleep time at creation time.

Examples:

$ openenv fork owner/source-space $ openenv fork owner/source-space –private $ openenv fork owner/source-space –repo-id myuser/my-fork $ openenv fork owner/source-space –set-env MODEL_ID=user/model –set-secret HF_TOKEN=hf_xxx $ openenv fork owner/source-space –hardware t4-medium

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.

openenv.cli.__main__.main() → None

Main entry point for the CLI.

CLI helpers

CLI utilities for OpenEnv command-line interface.

openenv.cli._cli_utils.validate_env_structure(env_dir: Path, strict: bool = False) → List[str]

Validate that the directory follows OpenEnv environment structure.

Args:

env_dir: Path to environment directory strict: If True, enforce all optional requirements

Returns:

List of validation warnings (empty if all checks pass)

Raises:

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).

openenv.cli._validation.build_local_validation_json_report(env_name: str, env_path: Path, is_valid: bool, issues: list[str], deployment_modes: dict[str, bool] | None = None) → dict[str, Any]

Build a JSON report for local environment validation.

openenv.cli._validation.format_validation_report(env_name: str, is_valid: bool, issues: list[str]) → str

Format a validation report for display.

Returns:

Formatted report string

openenv.cli._validation.get_deployment_modes(env_path: Path) → dict[str, bool]

Check which deployment modes are supported by the environment.

Returns:

Dictionary with deployment mode names and whether they’re supported

openenv.cli._validation.validate_multi_mode_deployment(env_path: Path) → tuple[bool, list[str]]

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

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

Returns:

Tuple of (is_valid, list of issues found)

openenv.cli._validation.validate_running_environment(base_url: str, timeout_s: float = 5.0) → dict[str, Any]

Validate a running OpenEnv server against runtime API standards.

The returned JSON report contains an overall pass/fail result and per-criterion outcomes that can be consumed in CI.