Add push command to OpenEnv CLI for deploying environments to Hugging Face Spaces

- Introduced `openenv push` command to validate and upload OpenEnv environments.
- Updated `README.md` and template files to include deployment instructions.
- Enhanced `pyproject.toml` with new dependencies: `pyyaml` and `huggingface_hub`.
- Modified import statements to support the new command structure.
- Added tests for the `push` command to ensure functionality and validation.

Author: zkwentz

README.md

@@ -143,6 +143,66 @@ To use an environment:
 
 See example scripts in `examples/` directory.
 
+## CLI Commands
+
+OpenEnv provides a command-line interface for managing environments:
+
+### `openenv init`
+
+Initialize a new OpenEnv environment:
+
+```bash
+openenv init my_game_env
+openenv init my_env --output-dir /path/to/projects
+```
+
+Creates a new directory with all necessary files based on the OpenEnv template.
+
+### `openenv push`
+
+Push an OpenEnv environment to Hugging Face Spaces:
+
+```bash
+# From the environment directory (where openenv.yaml is located)
+openenv push
+
+# With options
+openenv push --repo-id my-org/my-env --private
+openenv push --base-image ghcr.io/meta-pytorch/openenv-base:latest
+```
+
+The `openenv push` command:
+1. Validates that the directory is an OpenEnv environment (checks for `openenv.yaml`)
+2. Prepares a custom build for Hugging Face Docker space (enables web interface)
+3. Uploads to Hugging Face (ensuring you're logged in)
+
+**Prerequisites:**
+- Authenticate with Hugging Face: Set `HF_TOKEN` environment variable or the command will prompt for login
+
+**Options:**
+- `--directory`, `-d`: Directory containing the OpenEnv environment (defaults to current directory)
+- `--repo-id`, `-r`: Repository ID in format 'username/repo-name' (defaults to 'username/env-name' from openenv.yaml)
+- `--base-image`, `-b`: Base Docker image to use (overrides Dockerfile FROM)
+- `--private`: Deploy the space as private (default: public)
+
+After deployment, your space will be available at:
+`https://huggingface.co/spaces/<repo-id>`
+
+The deployed space includes:
+- **Web Interface** at `/web` - Interactive UI for exploring the environment
+- **API Documentation** at `/docs` - Full OpenAPI/Swagger interface
+- **Health Check** at `/health` - Container health monitoring
+
+### `openenv convert`
+
+Convert an existing environment to OpenEnv format:
+
+```bash
+openenv convert --env-path /path/to/env
+```
+
+See the [convert command documentation](src/openenv_cli/commands/convert.py) for more details.
+
 ## Design Principles
 
 1. **Separation of Concerns**: Clear client-server boundaries

pyproject.toml

@@ -14,7 +14,9 @@ dependencies = [
     "uvicorn>=0.24.0",
     "smolagents>=1.22.0,<2",
     "typer>=0.9.0",
-    "rich>=13.0.0"
+    "rich>=13.0.0",
+    "pyyaml>=6.0",
+    "huggingface_hub>=0.20.0"
 ]
 
 [project.scripts]

src/openenv_cli/__main__.py

@@ -17,6 +17,7 @@
 
 from openenv_cli.commands import convert
 from openenv_cli.commands import init
+from openenv_cli.commands import push
 
 # Create the main CLI app
 app = typer.Typer(
@@ -28,6 +29,7 @@
 # Register commands
 app.command(name="init", help="Initialize a new OpenEnv environment")(init.init)
 app.add_typer(convert.app, name="convert", help="Convert an existing environment to OpenEnv format")
+app.command(name="push", help="Push an OpenEnv environment to Hugging Face Spaces")(push.push)
 
 
 # Entry point for setuptools

src/openenv_cli/commands/__init__.py

@@ -6,7 +6,7 @@
 
 """OpenEnv CLI commands."""
 
-from openenv_cli.commands import convert, init
+from openenv_cli.commands import convert, init, push
 
-__all__ = ["convert", "init"]
+__all__ = ["convert", "init", "push"]