CLI reference¶

pygodide¶

Bundle your pygame app and run it in the browser with Pyodide.

Usage¶

pygodide [OPTIONS] COMMAND [ARGS]...

Arguments¶

No arguments available

Options¶

Name	Description	Required	Default
`--version`	Show the version and exit.	No	`False`
`--install-completion`	Install completion for the current shell.	No	-
`--show-completion`	Show completion for the current shell, to copy it or customize the installation.	No	-

Commands¶

Name	Description
`build`	Package a Pygame app to run in the browser.
`serve`	Serve a built app locally over HTTP.
`smoke`	Build and verify an app in a headless browser.

Subcommands¶

build¶

Bundle a Pygame app and generate the HTML and JS files needed to run it in the browser with Pyodide.

Usage¶

pygodide build [OPTIONS] {path}

Arguments¶

Name	Description	Required
`path`	Root directory of the Pygame app to build	Yes

Options¶

Name	Description	Required	Default
`--serve / --no-serve`	Whether to serve the built app after building	No	`no-serve`
`--app`	Entrypoint in 'module:callable' format. Overrides [tool.pygodide].app when provided.	No	-
`--dep`	Additional dependency requirement to include. Repeat for multiple dependencies.	No	-
`--auto-async / --no-auto-async`	Automatically adapt simple synchronous Pygame loops to yield to the browser event loop. Overrides [tool.pygodide].auto-async when provided.	No	-
`--clean`	Remove the build directory before building.	No	`False`
`--zip`	Create an itch.io-ready ZIP of the build output. Defaults to PROJECT_DIR/PROJECT_NAME.zip. Implies --clean.	No	`False`
`--zip-output`	Path for the itch.io ZIP. Only used with --zip.	No	-
`--canvas-width`	Canvas width in pixels (with --canvas-height). Alone: fixed box. With --canvas-fit: aspect ratio to scale into the viewport (useful when set_mode is not auto-discovered). Does not change set_mode. Overrides [tool.pygodide].canvas-width.	No	-
`--canvas-height`	Canvas height in pixels (with --canvas-width). Alone: fixed box. With --canvas-fit: aspect ratio for viewport scaling. Does not change set_mode. Overrides [tool.pygodide].canvas-height.	No	-
`--canvas-fit / --no-canvas-fit`	Scale to the largest viewport size that keeps aspect ratio. Aspect comes from --canvas-width/--canvas-height when set, else auto-discovered set_mode size. Overrides [tool.pygodide].canvas-fit. Cannot combine with --canvas-fill.	No	-
`--canvas-fill / --no-canvas-fill`	Stretch the canvas to fill the browser viewport (may change aspect ratio). Overrides [tool.pygodide].canvas-fill. Cannot combine with --canvas-fit.	No	-
`-p, --port`	Port for --serve (default 8000). Only valid together with --serve.	No	-

serve¶

Serve the built Pygodide app from the build directory.

Usage¶

pygodide serve [OPTIONS] {path}

Arguments¶

Name	Description	Required
`path`	Source directory or build directory to serve	Yes

Options¶

Name	Description	Required	Default
`-p, --port`	Port to listen on.	No	`8000`

smoke¶

Build and smoke-test an app in a headless browser.

Usage¶

pygodide smoke [OPTIONS] {path}

Arguments¶

Name	Description	Required
`path`	Source app directory to build and smoke test.	Yes

Options¶

Name	Description	Required	Default
`--suite`	Treat PATH as a directory of testing_manifest.yaml target fixtures and run all targets by default.	No	`False`
`-t, --target`	Only with --suite: filter the suite to a manifest name. Repeat to include multiple targets.	No	-
`--app`	Entrypoint in 'module:callable' format. Overrides [tool.pygodide].app when provided.	No	-
`--dep`	Additional dependency requirement to include. Repeat for multiple dependencies.	No	-
`--smoke-path`	URL path to load from the built app during the smoke test.	No	`/`
`--timeout-ms`	Milliseconds to wait for the ready log and loading status to clear.	No	`120000`
`--post-ready-ms`	Milliseconds to keep listening for errors after the ready log.	No	`500`
`--ready-log`	Console log message that marks the generated app as ready.	No	`[pygodide] ready`
`--build-only`	Build without launching Playwright.	No	`False`
`--auto-async / --no-auto-async`	Automatically adapt simple synchronous Pygame loops before smoke testing. Overrides [tool.pygodide].auto-async when provided.	No	-
`--canvas-width`	Canvas width in pixels (with --canvas-height). Alone: fixed box. With --canvas-fit: aspect ratio for viewport scaling. Overrides [tool.pygodide].canvas-width.	No	-
`--canvas-height`	Canvas height in pixels (with --canvas-width). Alone: fixed box. With --canvas-fit: aspect ratio for viewport scaling. Overrides [tool.pygodide].canvas-height.	No	-
`--canvas-fit / --no-canvas-fit`	Scale to the largest viewport size that keeps aspect ratio. Use with --canvas-width/--canvas-height when set_mode is not discovered. Overrides [tool.pygodide].canvas-fit.	No	-
`--canvas-fill / --no-canvas-fill`	Stretch the canvas to fill the browser viewport (may change aspect ratio). Overrides [tool.pygodide].canvas-fill.	No	-
`-v, --verbose`	Print build and smoke details to the console.	No	`False`