shipit-cli 0.21.3

Shipit CLI is the best way to build, serve and deploy your projects anywhere.

Shipit

Shipit is a CLI that automatically detects the type of project you are trying to run, builds it and runs it using Starlark definition files (called Shipit).

It can run builds locally, inside Docker, or through Wasmer, and bundles a one-command experience for common frameworks.

Quick Start

To use shipit, you'll need to have uv installed.

Install nothing globally; use uvx shipit-cli to run Shipit from anywhere.

uvx shipit-cli .

Running in auto mode will generate the Shipit file when needed, build the project, and can also run it. Shipit picks the safest builder automatically and falls back to Docker or Wasmer when requested:

• uvx shipit-cli . --wasmer builds locally and runs inside Wasmer.
• uvx shipit-cli . --docker builds it with Docker (you can customize the docker client as well, eg: --docker-client depot).
• uvx shipit-cli . --start launches the app after building.

You can combine them as needed:

uvx shipit-cli . --start --wasmer --skip-prepare

Commands

Default auto mode

Full pipeline in one command. Combine flags such as --regenerate to rewrite the Shipit file. Use --wasmer to run with Wasmer.

generate

uvx shipit-cli generate .

Create or refresh the Shipit file. Override build and run commands with --install-command, --build-command, or --start-command. Pick a exlicit provider with --use-provider.

plan

uvx shipit-cli plan --out plan.json

Evaluate the project and emit config, derived commands, and required services without building. Helpful for CI checks or debugging configuration.

build

uvx shipit-cli build

Run the build steps defined in Shipit. Append --wasmer to execute inside Wasmer, --docker to use Docker builds.

run

uvx shipit-cli run

Run explicit commands for the project. Use --start to run the start command, or pass one or more --command values. Combine with --wasmer for WebAssembly execution.

deploy

uvx shipit-cli deploy

Deploy a Wasmer package generated by shipit build --wasmer. Use --wasmer-deploy-config to write deployment metadata instead of publishing.

Supported Technologies

Shipit works with three execution environments:

• Local builder for fast, host-native builds.
• Docker builder when container isolation is required.
• Wasmer runner for portable WebAssembly packaging and deployment.

Development

Clone the repository and use the uv project environment.

uv run shipit . --start

Use any other subcommand during development by prefixing with uv run shipit, for example uv run shipit build . --wasmer. This keeps changes local while matching the published CLI behaviour.

Tests

Run the test suite with:

uv run pytest

You can run the e2e tests in parallel (-n 8) with:

uv run pytest -m e2e -v "tests/test_e2e.py" -s -n 8

The e2e tests will:

• Build the project (locally, or with docker)
• Run the project (locally or with Wasmer)
• Test that the project output (via http requests) is the correct one

Release Automation

Releases are automated with Release Please and PyPI Trusted Publishing.

Requirements:

• Enable GitHub Actions workflow permissions for creating pull requests in the repository settings. Release Please uses the built-in GITHUB_TOKEN.
• Configure PyPI Trusted Publishing for the shipit-cli project:
  • owner: wasmerio
  • repository: shipit
  • workflow: pypi-publish.yml
  • environment: pypi
• Create a GitHub environment named pypi. Add reviewers there if releases should require manual approval before publishing.

On each push to main, Release Please opens or updates a release PR based on Conventional Commits. When that PR is merged, it creates a GitHub release with a vX.Y.Z tag and dispatches the PyPI workflow for that tag with the built-in GITHUB_TOKEN. The PyPI workflow also supports manual dispatch for reruns. It:

• Runs regular test and e2e workflows.
• Validates that the tag version without the leading v matches:
  • project.version in pyproject.toml
  • version in src/shipit/version.py
• Builds the package and publishes to PyPI only if all checks pass.