Documentation

#Installation

Hatch ships as a single static binary. Download the archive for your platform, extract it, and place the executable somewhere on your PATH.

                        shell
                        
                    
# Linux
curl -LO https://get.tryhatch.dev/hatch-linux-x86_64.tar.gz
tar xzf hatch-linux-x86_64.tar.gz && sudo mv hatch /usr/local/bin/
hatch --version

#Start a project

Scaffold a fresh project with hatch init, or adopt an existing Flutter app with hatch migrate, which converts your pubspec.yaml into a hatch.json manifest. Then resolve and cache everything with hatch install.

                        shell
                        
                    
# start fresh…
hatch init my_app && cd my_app

# …or adopt an existing Flutter project
hatch migrate           # pubspec.yaml → hatch.json
hatch fvm use 3.35.2   # pin the Flutter version
hatch install

#The manifest

A small hatch.json (or hatch.yaml) declares your dependencies, SDK constraints, scripts, and profiles. Path dependencies point at local packages for monorepos; require-dev holds test-only packages.

                        hatch.json
                        
                    
{
  "name": "my_flutter_app",
  "version": "1.0.0",

  "sdk": {
    "flutter": "3.35.2",
    "dart": ">=3.5.0 <4.0.0"
  },

  "require": {
    "http": "^1.0.0",
    "provider": "^6.0.0",
    "local_package": { "version": "any", "path": "../packages/local_package" }
  },

  "require-dev": { "test": "^1.24.0" },

  "scripts": {
    "post-install": "dart run build_runner build",
    "test": ["flutter", "test"]
  }
}

#Commands

The core binary drives dependency resolution and toolchain management. Plugins register their own subcommands once installed.

Project

hatch init [name]: Scaffold a new project
hatch migrate: Convert pubspec.yaml to hatch.json
hatch install: Resolve + download + cache dependencies
hatch add <pkg> [ver]: Add a dependency (--dev for dev-only)
hatch remove <pkg>: Remove a dependency
hatch update [pkgs...]: Update some or all dependencies
hatch why <pkg>: Explain why a package is in the graph
hatch run <script>: Run a manifest script

Toolchain & plugins

hatch fvm <list|use|install|sync>: Manage Flutter SDKs via FVM
hatch sdk-update: Update Flutter / Dart constraints
hatch cache stats: Cache location, size, package count
hatch cache prune --aggressive: Re-apply debloat, trim to lockfile
hatch cache clear --force: Empty the machine-global cache
hatch plugin install <name>: Install a plugin from the registry
hatch plugin list: List installed plugins
hatch plugin remove <name>: Remove an installed plugin

#File purging

On extract, Hatch strips example apps, tests, docs, editor folders, and stray binaries, while always keeping lib/, bin/, tool/, the manifests, and README / LICENSE / CHANGELOG. It reads the pubspec to preserve declared assets, fonts, and real platform folders. Set HATCH_DEBLOAT=0 to disable.

                        .hatch.json – per-package overrides
                        
{ "hatch_package_version": 1, "keep": ["assets/**"], "strip": ["lib/legacy/**"] }

#Caching

One cache per machine, shared across every project, with debloated package trees, transient downloads, and version metadata. Relocate it with HATCH_CACHE_DIR; inspect and trim it with the cache subcommands.

                        shell
                        
                    
hatch cache stats              # location, size, package count
hatch cache list --detailed
hatch cache remove http 1.1.0
hatch cache prune --aggressive   # re-debloat, trim to lockfile
hatch cache clear --force

#Security

Every download must carry a checksum or the install aborts. Dependency scripts prompt on first run and remember the answer; non-interactive environments default to deny. Every bypass and trust decision is written to ~/.hatch/audit.log.

                        shell
                        
                    
# a download with no checksum aborts the install
hatch install
# bypass once (audited), never as a setting
hatch install --allow-unchecksummed

# non-interactive script trust (CI defaults to deny)
HATCH_TRUST_SCRIPTS=all hatch install

#Plugins

Plugins extend the core with new capabilities. Install one from the registry and Hatch fetches the right asset for your platform, verifies its checksum, and registers its subcommands. The flagship ios plugin builds and ships iOS without a Mac.

                        shell
                        
                    
hatch plugin install ios   # add a plugin from the registry
hatch plugin list          # what is installed
hatch plugin remove ios

#iOS plugin

Once installed with hatch plugin install ios, the plugin adds the hatch ios commands. A single command runs the full Apple pipeline – compile, assemble, sign, and upload – producing a TestFlight build entirely on Linux or Windows. Add your distribution certificate and an App Store Connect API key, and there is no Mac, no Transporter, and no password anywhere in the flow.

                        shell
                        
                    
# once: install the flagship plugin
hatch plugin install ios
hatch ios doctor      # check the toolchain

# build, sign and upload to TestFlight in one step
hatch ios build --bundle-id com.you.app --name "My App" --sign --distribution

# or upload an existing .ipa
hatch ios publish --ipa build/app.ipa

#Continuous integration

Because Hatch is a single binary with clean exit codes and non-interactive output, wiring it into CI is a matter of caching the toolchain and exporting your secrets.

                        .github/workflows/release.yml
                        
                    
- name: Ship to TestFlight
  run: hatch ios build --sign --upload
  env:
    HATCH_CERT:    ${{ secrets.DIST_CERT }}
    HATCH_API_KEY: ${{ secrets.ASC_API_KEY }}

Heads up

This is a living document for the public release. Command flags and output shown here illustrate the workflow and may change as the toolchain stabilises.