CLI Reference

PyGo CLI Reference

The PyGo CLI provides commands for project management, transpilation, and deployment.

Global Options

pygo [flags] <command> [args]

Flag	Description	Default
--verbose / -v	Enable verbose output	false
--config	Path to config file	./pygo.toml
--help / -h	Show help	—

Commands

pygo new <project-name>

Create a new PyGo project.

pygo new myapp
cd myapp
pygo dev

Options:

Flag	Description
--template	Template to use (web, api, cli)
--python-version	Python version constraint

---

pygo dev

Start the development server with hot reload.

pygo dev

Options:

Flag	Description	Default
--port / -p	Server port	8080
--host	Bind address	0.0.0.0
--no-transpile	Skip transpilation	false

---

pygo gen [file]

Transpile .pgo files into gen_py.py and gen_go.go.

# Transpile all .pgo files
pygo gen

# Transpile specific file
pygo gen app/web/app.pgo

Transpilation targets:

Flag	Target	Output
--go	Go backend	gen_go.go
--python	Python backend	gen_py.py
--both	Both backends	gen_go.go + gen_py.py

---

pygo build

Build the project for production.

# Build with embedded Python
pygo build --embed-python

# Build Go-only (no Python runtime)
pygo build --go-only

Options:

Flag	Description
--embed-python	Embed Python interpreter
--go-only	Generate Go binary only
--output / -o	Output path
--compress	Compress binary

---

pygo test

Run tests.

pygo test
pygo test -v ./...

Options:

Flag	Description
--python	Run Python tests
--go	Run Go tests
--coverage	Generate coverage report

---

pygo worker [script.py]

Start the background job worker (Python context).

# Start worker for jobs.py
pygo worker app/core/jobs.py

# With concurrency
pygo worker --concurrency 10 app/core/jobs.py

---

pygo module install <module-name>

Install a PyGo module from the registry.

# Install a module
pygo module install pygo-i18n

# Install specific version
pygo module install pygo-i18n@v0.1.0

# Install with peer dependencies
pygo module install pygo-erp

Options:

Flag	Description
--version	Specific version
--peer-deps	Install peer dependencies (default: auto)

---

pygo module list

List all installed modules.

pygo module list

# Output:
# NAME          VERSION  DESCRIPTION
# pygo-framework  1.2.0  Full-stack Go+Python framework
# pygo-i18n       0.1.0  Internationalization

Options:

Flag	Description
--outdated	Show modules with newer versions
--global	Include globally installed modules

---

pygo module search <query>

Search the PyGo module registry.

pygo module search i18n
pygo module search "background jobs"

---

pygo module uninstall <module-name>

Uninstall a module.

pygo module uninstall pygo-i18n

---

Registry

PyGo modules are fetched from the static JSON registry:

https://raw.githubusercontent.com/pygo-labs/pygo-registry/main/registry.json

Available modules include:

Module	Core Package	Description
pygo-framework	core, http, storage, cache, queue, logger, validator, mailer, backup	Core framework
pygo-ui	components	44 UI components (HTMX + Tailwind)
pygo-admin	admin	Admin panel components (DataTable, FormBuilder)
pygo-mcp	mcp	Model Context Protocol server
pygo-i18n	i18n	Internationalization
pygo-docs	—	Documentation site (Astro Starlight)

---

Configuration

PyGo reads configuration from pygo.toml (TOML format):

[project]
name = "myapp"
version = "0.1.0"

[server]
host = "0.0.0.0"
port = 8080

[database]
url = "sqlite:///app.db"

[logger]
format = "json"
level = "info"

[queue]
backend = "memory"  # or "redis"
redis_url = "redis://localhost:6379"

Environment Variables

Variable	Description	Default
PYGO_ENV	Environment (dev, prod)	dev
DATABASE_URL	Database connection string	—
REDIS_URL	Redis connection string	—
PYGO_JWT_SECRET	JWT signing secret	—