Command line

This page lists the pig command-line verbs and subcommands, and the pig docs commands for the embedded reference bundle. Command line by example runs the common ones and shows their output. PiG follows the command line of Pi 1.5.0 (Pi's command line reference). Run pig --help or append --help to a command for the exact interface of the installed binary.

CLI verbs

pig [options] [prompt]

Generic subcommands

Product distributions may contribute additional top-level or nested command paths. Core command paths always win; use pig --help and the product's focused docs for contributed commands.

pig install accepts one source. Missing sources and unknown options show the ordinary single-source usage, except that --validate-only with no source checks the configured local Packages (D216). Use pig install --help for the separate multi-source --validate-only forms (D28).

Options

These options apply to pig [options] [prompt]. Run pig --help for the full list.

Extensions can register their own options, such as --plan from a plan-mode extension.

PiG resolves local extension, Skill, prompt-template, and theme arguments relative to the launch directory. It leaves package-source and remote-URL arguments unchanged during this step.

File arguments

Use @path to attach a file to the initial prompt:

pig -p @notes.txt "Summarize these notes."

Text files use <file name="/absolute/path">\ncontent\n</file>\n. PiG adds the newline before </file> even when the file already ends with a newline, as Pi does. It skips empty files. The first positional prompt follows the closing tag's newline without an additional separator.

Tools

pig --tools read,grep,find,ls -p "Review the code in src/"

The tool options select the tools the model can call for one run. See Settings to change the default selection.

Without these options, PiG enables read, bash, edit, and write, unless the defaultTools setting changes the set. Extension tools stay enabled. An explicit empty active tool set also stays empty in the system prompt, including after reload.

Two built-in extensions add tools that are off by default. codemode runs JavaScript that calls the other tools, and tool_search finds tools that are not declared to the model. The mcp extension turns them on when an MCP server needs them. To enable them yourself, name them in --tools or in the defaultTools setting, for example pig --tools read,bash,edit,write,codemode. See Codemode and tool search and MCP servers.

<a id="mcp-tools"></a>

--tools selects the tools declared to the model. It does not remove MCP tools, whose reach is set by their exposure: pig --tools read,codemode keeps every MCP tool callable from codemode scripts. An MCP tool that no entry names or matches is never declared directly, whatever its exposure; only tool_search, if listed, can load it. Once an entry starts with mcp__, --tools filters MCP tools too, so this keeps only the tools of the radius server:

pig --tools read,bash,codemode,'mcp__radius__*'

The MCP resource tools (list_mcp_resources, list_mcp_resource_templates, read_mcp_resource) count as MCP tools. To remove MCP tools, use --exclude-tools 'mcp__*' or --no-mcp.

For a read-only session, allow only the tools that cannot change files:

pig --tools read,grep,find,ls

To keep the default set without one tool, exclude it:

pig --exclude-tools bash

Custom update command

When a wrapper or another package manager provides PiG, set PI_SELF_UPDATE_COMMAND (or PIG_SELF_UPDATE_COMMAND) so pig update runs its update command:

export PI_SELF_UPDATE_COMMAND="mise use -g npm:{packageName}@{version}"

pig update checks the signed release manifest first and runs the command only when the release is newer (or with --force), after printing the release note. {packageName}, {version} and {installSpec} ({packageName}@{version}) come from that release. The value is split on whitespace. For arguments with spaces, use the selfUpdateCommand setting in ~/.pig/agent/settings.json, an argv array such as ["nix", "profile", "upgrade", "pig"]. A project's settings file is never read for it.

The configured command is your explicit choice of the one owner of the update. It replaces PiG's own tier selection (standalone replace, package manager, immutable Piglet Binary, container image) and never falls through to one of them. Without an update source there is no release to fill the placeholders from, so the command does not run. Exit code 0 does not prove an update: pig update prints Updated pig from X to Y when pig --version reports Y (from the replaced executable, else from PATH), and otherwise warns with the version it found.

pig docs

Stock PiG materializes its reference docs under ~/.pig/docs/ so the coding agent can read the API implemented by the running binary.

pig docs              # sync + summary (default)
pig docs sync         # force re-sync
pig docs path         # write the bundle if missing, print its directory
pig docs list         # list available files
pig docs show <name>  # print one doc to stdout

Each build writes its bundle to its own directory, ~/.pig/docs/bundle-<hash>/, named by the content hash of its pages. Two PiG builds that share a config root (two installed versions, or Stock PiG beside a Piglet Binary) each keep their own bundle, so neither rewrites the other's docs and a running session's docs never change. A sync keeps the four most recently used bundles and removes older ones. Pages an older PiG wrote directly in ~/.pig/docs/ stay for that version. PiG writes the bundle before anything other than PiG can read it: before the first tool call, before an extension starts, at interactive and RPC start, and for pig docs path. A print or JSON run that calls no tool and starts no extension writes nothing. When the bundle is already there, a start reads one marker file.

When the config root cannot be written and holds no bundle of the running build, startup writes nothing and prints nothing (D157). The system prompt then has no docs section, and no other text names a docs page, because Pi's docs always exist and PiG does not name files that are not there (D22). pig docs show still prints the embedded pages. To give a read-only image its docs, run pig docs sync while the config root is still writable. pig diagnose reports a read-only config root and what PiG does not write there.