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 . --wasmerbuilds locally and runs inside Wasmer.uvx shipit-cli . --dockerbuilds it with Docker (you can customize the docker client as well, eg:--docker-client depot).uvx shipit-cli . --startlaunches 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 an explicit
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.
The Shipit file
shipit generate writes a small, editable Starlark file that pairs a
provider build with a serve:
load("//shipit/tools:python.shipit", "python_build", "python_serve")
build = python_build(config)
python_serve(config, build, name = "my-app")
The file is yours: add steps around the build (build_pre / build_post),
extend the runtime (extra_deps, extra_env), attach services, or compose
builds and serves from different providers (a Hugo build served by the
shared static serve, a PHP build with a Node asset build folded in). Any
config field can also be overridden without editing anything, via SHIPIT_*
environment variables (e.g. SHIPIT_PHPIX=true) or --config JSON.
See docs/shipit-files.md for the full format
reference: builtins, file_exists(), load labels, the serve override
surface, and composition examples.
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
You can also run one technology slice at a time with e2e_static,
e2e_staticpython, e2e_staticnode1, e2e_staticnode2, e2e_python,
e2e_node, or e2e_php, for example:
uv run pytest -m "e2e and e2e_staticnode1" -v "tests/test_e2e.py" -s -n 4
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-cliproject:- owner:
wasmerio - repository:
shipit - workflow:
pypi-publish.yml - environment:
pypi
- owner:
- 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 tests, excluding e2e tests.
- Validates that the tag version without the leading
vmatches:project.versioninpyproject.tomlversioninsrc/shipit/version.py
- Builds the package and publishes to PyPI only if all checks pass.
2 maintainers
Metadata
2 maintainers
Release files for shipit-cli 0.23.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| shipit_cli-0.23.0.tar.gz | 114.4 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| shipit_cli-0.23.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 208.6 kB
Release files / shipit_cli-0.23.0.tar.gz
| Download URL | shipit_cli-0.23.0.tar.gz |
|---|---|
| Size | 114.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
f2f8ff13fd070976c90bbadc27c057d60811f24a5039963c6a72245ece0eb41c
|
|
BLAKE2b-256 checksum How to use checksums |
c93334a60bc669107427453375851a280eff89ea355fc8dcc86edb7c7f0eb8c1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 23, 2026.
Transparency logRelease files / shipit_cli-0.23.0-py3-none-any.whl
| Download URL | shipit_cli-0.23.0-py3-none-any.whl |
|---|---|
| Size | 94.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
bbe6fef817770a2b27e617671d07804f7654cc1155912ad53877a21b48d80d47
|
|
BLAKE2b-256 checksum How to use checksums |
b0e16f2cbc0893745c415978e057d7f6ebae7bbebd1b7ce14a50c0f456e63120
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 23, 2026.
Transparency log
