openenv/pr_749/en/reference/cli.md

# 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](../getting_started/environment-builder) guide.

## `openenv init`[[openenv.cli.commands.init]]

#### openenv.cli.commands.init[[openenv.cli.commands.init]]

[Source](https://github.com/huggingface/openenv/blob/vr_749/openenv/cli/commands/init.py#L396)

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`[[openenv.cli.commands.build]]

#### openenv.cli.commands.build[[openenv.cli.commands.build]]

[Source](https://github.com/huggingface/openenv/blob/vr_749/openenv/cli/commands/build.py#L331)

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.cli.commands.validate]]

#### openenv.cli.commands.validate[[openenv.cli.commands.validate]]

[Source](https://github.com/huggingface/openenv/blob/vr_749/openenv/cli/commands/validate.py#L34)

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`[[openenv.cli.commands.push]]

#### openenv.cli.commands.push[[openenv.cli.commands.push]]

[Source](https://github.com/huggingface/openenv/blob/vr_749/openenv/cli/commands/push.py#L530)

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

# Push with GPU hardware
$ openenv push --hardware t4-medium

# Set a public Space variable (overrides openenv.yaml variables:)
$ openenv push -e OPENSPIEL_GAME=tic_tac_toe -e MAX_STEPS=100

# Set a private Space secret (value never logged)
$ openenv push --secret OPENAI_API_KEY=sk-...

## `openenv serve`[[openenv.cli.commands.serve]]

#### openenv.cli.commands.serve[[openenv.cli.commands.serve]]

[Source](https://github.com/huggingface/openenv/blob/vr_749/openenv/cli/commands/serve.py#L21)

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

## `openenv fork`[[openenv.cli.commands.fork]]

#### openenv.cli.commands.fork[[openenv.cli.commands.fork]]

[Source](https://github.com/huggingface/openenv/blob/vr_749/openenv/cli/commands/fork.py#L86)

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

## `openenv skills`[[openenv.cli.commands.skills.skills_add]]

Installs an `openenv-cli` skill into your AI assistant's skills directory so
it knows the `openenv` CLI is available and what each command does. Supports
Claude Code, Cursor, Codex, and OpenCode.

**Install for a single assistant (project-local):**

```bash
openenv skills add --claude    # → .claude/skills/openenv-cli/
openenv skills add --cursor    # → .cursor/skills/openenv-cli/
openenv skills add --codex     # → .codex/skills/openenv-cli/
openenv skills add --opencode  # → .opencode/skills/openenv-cli/
```

Multiple flags can be combined — `openenv skills add --claude --cursor` installs
for both at once. The skill file is written to a central location
(`.agents/skills/openenv-cli/`) and each agent directory gets a symlink, so
there is only one copy to update.

**Install globally (user-level, across all projects):**

```bash
openenv skills add --claude --global  # → ~/.claude/skills/openenv-cli/
```

**Overwrite an existing installation** (e.g. after upgrading `openenv`):

```bash
openenv skills add --claude --force
```

**Preview the skill content without installing:**

```bash
openenv skills preview
```

**Install to a custom path** (for non-standard agent setups):

```bash
openenv skills add --dest /path/to/my-agent/skills/
```

#### openenv.cli.commands.skills.skills_add[[openenv.cli.commands.skills.skills_add]]

[Source](https://github.com/huggingface/openenv/blob/vr_749/openenv/cli/commands/skills.py#L139)

Install OpenEnv CLI skill for AI assistants.

#### openenv.cli.commands.skills.skills_preview[[openenv.cli.commands.skills.skills_preview]]

[Source](https://github.com/huggingface/openenv/blob/vr_749/openenv/cli/commands/skills.py#L133)

Print generated SKILL.md content.

# API Reference

## Entry point[[openenv.cli.__main__.main]]

#### openenv.cli.__main__.main[[openenv.cli.__main__.main]]

[Source](https://github.com/huggingface/openenv/blob/vr_749/openenv/cli/__main__.py#L66)

Main entry point for the CLI.

## CLI helpers[[openenv.cli._cli_utils.validate_env_structure]]

#### openenv.cli._cli_utils.validate_env_structure[[openenv.cli._cli_utils.validate_env_structure]]

[Source](https://github.com/huggingface/openenv/blob/vr_749/openenv/cli/_cli_utils.py#L18)

Validate that the directory follows OpenEnv environment structure.

**Parameters:**

env_dir : Path to environment directory

strict : If True, enforce all optional requirements

**Returns:**

List of validation warnings (empty if all checks pass)

## Validation utilities[[openenv.cli._validation.validate_running_environment]]

#### openenv.cli._validation.validate_running_environment[[openenv.cli._validation.validate_running_environment]]

[Source](https://github.com/huggingface/openenv/blob/vr_749/openenv/cli/_validation.py#L103)

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.

#### openenv.cli._validation.validate_multi_mode_deployment[[openenv.cli._validation.validate_multi_mode_deployment]]

[Source](https://github.com/huggingface/openenv/blob/vr_749/openenv/cli/_validation.py#L504)

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.get_deployment_modes[[openenv.cli._validation.get_deployment_modes]]

[Source](https://github.com/huggingface/openenv/blob/vr_749/openenv/cli/_validation.py#L579)

Check which deployment modes are supported by the environment.

**Returns:**

Dictionary with deployment mode names and whether they're supported

#### openenv.cli._validation.format_validation_report[[openenv.cli._validation.format_validation_report]]

[Source](https://github.com/huggingface/openenv/blob/vr_749/openenv/cli/_validation.py#L608)

Format a validation report for display.

**Returns:**

Formatted report string

#### openenv.cli._validation.build_local_validation_json_report[[openenv.cli._validation.build_local_validation_json_report]]

[Source](https://github.com/huggingface/openenv/blob/vr_749/openenv/cli/_validation.py#L626)

Build a JSON report for local environment validation.