Piglet lifecycle

A Piglet goes through nine stages, from a YAML file you write to an agent that other people install and update. This page names each stage. It gives one command for each stage and states what the command changes.

Piglets explain the file. Piglet Binaries explain the executable. Publish a Package or Piglet explains npm publication.

author -> validate -> run -> inspect -> register -> build -> sign and verify -> publish -> install and update
  file      check     try     look      copy to     script    key, signature,   GitHub     add, pull,
            schema    it      at it     ~/.pig      or        trust             Release    update
                                        /piglets    Binary                      or npm

The stages at a glance

Stage	Command	What it changes	Release record
1. Author	Edit the YAML file. `pig piglet schema` prints the schema.	Your file.	No record.
2. Validate	`pig piglet validate <name\\|path>`	Nothing.	No record.
3. Run	`pig --piglet <name\\|path>`	Nothing on disk, except the Session you create.	No record.
4. Inspect	`pig piglet show <name\\|path>`	Nothing.	Lists the records that exist.
5. Register	`pig piglet add <path\\|npm:ref\\|git:ref>`	Copies the file into `~/.pig/piglets/`. A remote source also writes `<name>.origin.json`.	The origin file records the source, the resolved version and the digest.
6. Build	`pig piglet build <name> --format script\\|binary --out <path>`	Writes the script or the Binary.	A Binary writes a record. A script writes none.
7. Sign and verify	`pig piglet keygen`, `build --sign-key`, `pig piglet verify`	Adds a signature to the Binary.	The signature covers the record.
8. Publish	`pig piglet publish <name\\|path> --to github\\|npm`	Creates a GitHub Release or an npm package. A dry run changes nothing.	Writes a publication receipt.
9. Install and update	`pig piglet add npm:<name>`, `pig piglet pull <release>`, `pig piglet update <name>`	Installs the Piglet source or the signed Binary.	Pins the signer and keeps the signed index.

Planned stages are marked in the sections below and in Planned stages.

1. Author

Write one YAML file. Only name is required. This file limits the built-in tools to a read-only set:

name: reviewer
description: A read-only code reviewer.
tools: [read, grep, find]
systemPrompt:
  text: Review the code. Do not change files.
release:
  version: 0.1.0

Print the closed schema of the file:

pig piglet schema

release.version is the version of the Piglet release. Set it before you build or publish. See Piglets for every field.

2. Validate

pig piglet validate ./reviewer.yaml

OK: reviewer (./reviewer.yaml): 0 extension(s), 0 skill(s)

Validation checks the schema. It also resolves every origin. It changes nothing.

3. Run

pig --piglet ./reviewer.yaml

This starts PiG with the Piglet from the file. The Piglet does not become the default. A bare pig still runs Stock PiG.

4. Inspect

pig piglet show ./reviewer.yaml

Piglet: reviewer
  A read-only code reviewer.
Source: ./reviewer.yaml
Built-in tools: read, grep, find (a limit; it does not activate a tool)
Active by default: read

System prompt: Review the code. Do not change files. (37 bytes)

Release:
  version: 0.1.0

In an interactive session, an active Piglet adds the read-only command /piglet.

Piglet tool scope

The tools list is a ceiling. The Piglet keeps at most the tools in the list. A run activates only the default tools that the list keeps. In the example, Active by default is read, because grep and find are not default tools.

The Piglet scope removes tools from the tool registry of the Session. This is the registry that --tools and --exclude-tools also filter. A tool that the scope removes is gone. The model cannot call it. A codemode script cannot call it. tool_search cannot find it. See Tool scope for the rules for extension tools and MCP tools.

5. Register

Copy the file into your Piglet directory so that you can select it by name:

pig piglet add ./reviewer.yaml
pig piglet list
pig --piglet reviewer

Added reviewer (0 extensions, 0 skills) → ~/.pig/piglets/reviewer.yaml
NAME      SCOPE  SOURCE                      BINARY  IMAGE  DESCRIPTION
reviewer  user   ~/.pig/piglets/reviewer.yaml  -       -      A read-only code reviewer.

pig piglet add also takes a remote source:

pig piglet add npm:@acme/review@^1.0.0
pig piglet add git:https://github.com/acme/review.git@v2.0.0

A remote source writes <name>.origin.json next to the Piglet. The file records the exact version or commit and the digest. See Validate and register.

6. Build

A script is a thin launcher. A Piglet Binary is one executable that contains PiG and the Piglet:

pig piglet build reviewer --format script --out ./run-reviewer
pig piglet build reviewer --format binary --out ./pig-reviewer

A script writes no record. A Binary writes a record and a managed copy under ~/.pig/receipts/piglets/ and ~/.pig/artifacts/piglets/. pig piglet show reviewer lists them after the build:

Piglet Binaries:
  linux/amd64  version=0.1.0  build-checks-passed=true
    record=~/.pig/receipts/piglets/reviewer/<source digest>/0.1.0/piglet-binary/linux-amd64/<record>.json
    artifact=~/.pig/artifacts/piglets/reviewer/<source digest>/0.1.0/linux-amd64/<digest>/pig-reviewer

The native builder compiles PiG with the Go toolchain on your computer. See Build outputs for the builders and their prerequisites.

Overlay Piglets

A Piglet Binary behaves as stock PiG started with its own Piglet. It accepts one more Piglet at launch as an overlay, with --piglet, PIG_PIGLET_PATH or PIG_PIGLET_NAME. To make a Binary refuse the overlay selectors, --system-prompt, -e, the package commands and pig mcp add, and to remove its ambient discovery, settings.extensions and mcp.json servers, set build.closed: true in the Piglet that you build. The next example is an open Binary:

name: pig-base
tools: [read, grep, find]
systemPrompt:
  text: Base.

The Binary takes an overlay with --piglet:

pig piglet build ./base.yaml --format binary --out ./pig-base
./pig-base --piglet ./extra.yaml

An overlay merges onto the Piglet of the Binary exactly as an extends child merges onto its base. An overlay file has an extends block with no source. Stock pig piglet validate rejects such a file by design, because it has no base to extend:

FAIL: Piglet extra.yaml: extends.source is required unless a Piglet Binary that is not built closed runs the Piglet as an overlay

An overlay can replace the system prompt. It can remove members with extends.remove. It can widen the ceilings only with extends.allowWiden: true.

The Binary refuses only the parts that its build compiled in. It names the field and the reason. Two examples:

remove.strip.extensions: "mcp" is absent
strip.extensions: "mcp" is compiled out of Piglet Binary "pig-nomcp" (build tag pig_strip_mcp), so its code is not in the Binary; an overlay cannot re-enable it

The first message means that the Binary does not strip mcp, so the overlay has nothing to remove. The second message means that the build removed the mcp code from the executable. An overlay cannot bring that code back. See Accept overlay Piglets for the full rules.

build.closed is part of the baked Piglet. A change to it changes the Piglet digest in the record. A closed Binary refuses the overlay selectors, -e, pig install, pig remove, pig update --extensions and pig mcp add, and each refusal names build.closed.

7. Sign and verify

Create an Ed25519 key pair once. Keep the private file secret and publish the .pub file:

pig piglet keygen ./reviewer-signing.key

Sign during the build:

pig piglet build reviewer --format binary --out ./pig-reviewer --sign-key ./reviewer-signing.key

Check the file without running it:

pig verify ./pig-reviewer
pig piglet verify ./pig-reviewer --source reviewer

Piglet Binary: ./pig-reviewer
Signature: signed by ed25519:<key-id> (not in your Piglet trust store: this proves it is unchanged since that key signed it, not who holds the key)
Provenance: matches ~/.pig/piglets/reviewer.yaml
Signed manifest:
  Piglet: reviewer 0.1.0
  target: linux/amd64
  Pig: 0.5.3
  Piglet definition: sha256:<digest>
  resolution record: sha256:<digest>
  component plan: sha256:<digest>
  executable: sha256:<digest> (<size> bytes)

To attach a local identity to a key, trust it. To require signatures, turn the policy on:

pig piglet trust add ./reviewer-signing.key.pub
pig piglet trust list
pig piglet trust require on

See Sign a Binary.

What changes the release record

The signed manifest above names the parts of the release record. Each edit changes one or more of them:

You change	What changes
`release.version`	The version in the record path, the GitHub tag `v<release.version>`, and the npm version.
The Piglet file	The source digest. The record path contains the source digest, so a new source gets a new record.
A prompt file, a skill, or a base Piglet that the Piglet names	The Piglet definition digest. `pig piglet verify --source` fails until you rebuild.
The extensions or their origins	The component plan and the resolution record.
`build.closed`	The Piglet definition digest.
The target (`--targets`)	A separate record and Binary for each target.
The PiG version that builds the Binary	The `Pig:` line of the manifest.

A script never has a record. Rebuild a Binary after every change in this table.

8. Publish

Publish signed Binaries to a GitHub Release:

pig piglet publish reviewer --to github --repo acme/reviewer --sign-key ./reviewer-signing.key

Publish the source to npm:

pig piglet publish ./reviewer.yaml --to npm

Both commands are dry runs until you add --yes. The GitHub command uses the GitHub CLI (gh). It stops with an error when gh is not on PATH. The npm dry run prints the package that it would publish:

Piglet: reviewer@0.1.0 (not on npm yet)
Signed Binary: none recorded
...
Would run: npm publish /tmp/pig-piglet-npm-<id> --ignore-scripts
Dry run only; rerun with --yes to publish.

npm refuses a version that exists. Raise release.version before you publish again. See Publish to GitHub Releases and Publish a Package or Piglet.

9. Install and update

A user installs the source from npm or Git. A user installs a signed Binary from a GitHub Release:

pig piglet add npm:@acme/review@^1.0.0
pig piglet pull github:acme/reviewer@0.1.0
pig piglet update reviewer

pig piglet pull verifies the signed release index, the signature of the Binary and the checksums before it installs anything. The first pull pins the signer. A later signer change needs --accept-signer <key-id>.

pig piglet update <name> updates a signed GitHub Binary that pig piglet pull installed. It stays inside the signed namespace of that Binary. It does not update a source Piglet. See Pull a published Binary.

Planned stages

These commands do not work in this release. Each one fails with a clear message and writes nothing:

Planned	Today
`pig piglet pull <name>`, a pull by installed Piglet name	`pig piglet pull` needs a release index URL or a GitHub release reference.
`pig piglet build <name> --format image` (a Piglet Image)	Fails with `Piglet Image build is not implemented`.
`pig piglet build <name> --locked`	Fails with `--locked and --record Piglet artifact builds are not implemented`.
`pig piglet build <name> --record <path>`	The same failure as `--locked`.

See Planned stages in Piglets.

PiG Documentation