Skip to content

For the complete documentation index, see llms.txt.

The pig CLI reference

The pig CLI manages the source and generated plugins in an Instruction Hub. Install the toolchain with Python 3.11 or later using the setup guide. The package exposes equivalent pig and promptless-instruction-hub commands.

Run pig --help or pig <command> --help to see the options your installed version accepts. Every command on this page except pig status and pig cloud-bundle takes --hub PATH, the hub’s root directory, which defaults to the current directory.

CommandChanges files?Result
initYesCreates missing hub configuration and directories
scanYesImports supported assets and replaces the context inventory
validateNoChecks source configuration and asset references
verifyNo changes to the hubValidates and compiles a temporary release
buildYes, except with --checkWrites distribution files and manifests
set-versionYesUpdates the shared version in hub.yaml
statusNoReads local release metadata
cloud-bundleYes, writes one new ZIPPackages a cloud trace capture plugin for Claude Code

These commands do not install plugins into agents, enroll hosts, or deploy the analyzer. Publishing runs through GitHub or GitLab CI; there is no public pig publish command.

Create a hub with the mandatory plugins/pig.yaml, asset directories, and output directories. Existing files are preserved. The initial configuration includes all four targets and turns trace ingestion off.

Terminal window
pig init --hub ./acme-instruction-hub \
--org Acme \
--marketplace-id acme-instruction-hub \
--marketplace-name "Acme Instruction Hub" \
--version 0.1.0
OptionDefaultMeaning
--hub PATHCurrent directoryHub to initialize
--org NAMERequiredName of the organization that owns the hub
--marketplace-id IDThe organization name in kebab-case, followed by -instruction-hubStable marketplace identifier
--marketplace-name NAMEThe organization name followed by Instruction HubMarketplace display name
--version VERSION0.1.0Initial shared plugin version

Use marketplace.id and marketplace.name in hub.yaml for marketplace identity. Each plugins/*.yaml file has its own literal id and display name; no organization prefix is added automatically. version applies to the whole hub, and stable_plugins selects which plugins to release.

Import reusable assets from one source directory into a hub:

Terminal window
pig scan --hub ./acme-instruction-hub --source ./acme-docs
OptionDefaultMeaning
--hub PATHCurrent directoryHub to import into
--source PATHCurrent directoryRepository to import assets from

Pass both paths when the source repository and the hub are different directories. The scanner handles each kind of source file as follows:

In the source repositoryWhat scan does
Skills directly under .agents/skills/, .claude/skills/, or .cursor/skills/Imports each skill with its supporting files
A root .mcp.json, mcp.json, mcp.yaml, or mcp.ymlImports the first match as the MCP configuration
.cursor/mcp.jsonImports it when the root MCP configuration doesn’t already cover it
Root AGENTS.md, CLAUDE.md, and GEMINI.mdRecords each file’s content identity and size in hub.repo-context.json, without converting it into shared instructions
Other skill locations, rules, commands, hooks, and subagent definitionsNothing. Migrate them by hand.

Imported assets are added to the pig plugin’s includes list.

Scan writes to the hub. Reusing a skill ID replaces that destination skill directory; recognized MCP destinations and the context inventory can also be replaced. The command does not merge conflicting instructions or edit the source repository. Review each source’s import before scanning another. Follow Migrate existing instructions for a safe sequence.

Check source configuration, plugin definitions, referenced assets, target support declarations, file restrictions, and recognized MCP configuration constraints:

Terminal window
pig validate --hub ./acme-instruction-hub
OptionDefaultMeaning
--hub PATHCurrent directoryHub to validate

A successful result reports the number of stable assets. It does not compile the plugins or prove that the instructions behave correctly in an agent. Checks reject disallowed symlinks and recognized literal-secret patterns; they are not a comprehensive secret scanner. Review imported credentials separately.

Validate the hub, compile all selected targets in a temporary directory, and report the resulting release identity:

Terminal window
pig verify --hub ./acme-instruction-hub
OptionDefaultMeaning
--hub PATHCurrent directoryHub to verify

Use this before committing or reviewing instruction changes. It leaves the hub’s working files unchanged. A successful compile verifies generated structure, not marketplace authentication, desktop installation, or the quality of the agent’s work.

Compile each plugin in stable_plugins for every target in targets:

Terminal window
pig build --hub ./acme-instruction-hub
OptionDefaultMeaning
--hub PATHCurrent directoryHub to build
--checkOffCompare the existing generated output with a fresh compilation, without rewriting it

The output includes dist/<target>/<plugin-id>/, target marketplace manifests where supported, and release metadata. Keep authored changes in assets/, plugins/, and hub.yaml, because a later build can replace generated files.

With --check, a stale or missing generated file fails the command:

Terminal window
pig build --hub ./acme-instruction-hub --check

Use --check in a workflow that deliberately checks generated artifacts. For an authoring branch that leaves generated output to CI, use pig verify.

Update hub.yaml to a chosen shared plugin version:

Terminal window
pig set-version --hub ./acme-instruction-hub --version 0.2.0
pig verify --hub ./acme-instruction-hub
OptionDefaultMeaning
--hub PATHCurrent directoryHub to update
--version VERSIONRequiredNew shared plugin version

Commit the change through the normal review process. The command does not build or publish; publishing resolves the next release against the previous stable version and synchronizes generated versions.

Print release metadata as JSON from a local manifest:

Terminal window
pig status --manifest ./acme-instruction-hub/hub.release.json
OptionDefaultMeaning
--manifest PATHhub.release.json in the current directoryRelease manifest to read

This command has no --hub option. Run a build or use a release checkout before reading its manifest. pig status does not query installed agents, host enrollment, or the analyzer.

Package a Claude Code plugin that captures traces from cloud agent executions under a cloud integration grant:

Terminal window
pig cloud-bundle \
--worker-url https://traces.acme.example \
--provider claude_tag \
--integration-id YOUR_INTEGRATION_ID \
--transport proxy \
--output pig-cloud-capture.zip
OptionDefaultMeaning
--worker-url URLRequiredThe analyzer’s HTTPS origin, with no path, query, or credentials
--provider IDRequiredThe grant’s provider, such as claude_tag
--integration-id IDRequiredThe grant’s Integration ID from Settings → Cloud integrations
--transport MODEsecretproxy when the provider’s connection adds the token, secret when the sandbox supplies it
--output PATHRequiredA new file ending in .zip; the command fails if the file exists

The ZIP holds public configuration, the collector, and its hooks. It contains no credentials. The command doesn’t need a hub, and it doesn’t create a grant or check that the analyzer is reachable. See Capture traces from cloud agents.

A failed command prints an error: message. Read the file path and asset reference in it first. These are the common causes:

CauseWhat to check
A missing skill:<id> referenceThe plugin’s includes list and the skill directories under assets/skills/
A duplicate plugin IDThe id in each plugins/*.yaml file. Every plugin needs its own.
An unsupported asset conversionThe asset and target the message names
Stale generated output with build --checkRun pig build and commit the generated files, or use pig verify on a branch that leaves generated output to CI

Correct the source files and rerun pig validate and pig verify. Once they pass, continue to publishing and installation and test one installed skill in a real task.