CLI Output & Errors

The builder CLI is AI-first by design: every command has a machine-readable JSON mode, and every error carries a structured code with actionable suggestions. This page documents the user-facing output contract — formats, theming, verbosity — and the full error and exit-code reference.

Output formats

The CLI has two output formats, selected by the global --output flag:

Format	Selected by	Behaviour
pretty	--output=pretty, or default when stdout is a terminal	Human-readable, themed output: headings, paths, success/warning/error lines rendered with the active color theme.
json	--output=json, or default when stdout is not a terminal (pipes, CI)	NDJSON for CI/pipes and AI consumption. Machine-readable envelopes are written to stdout; human “chrome” (warnings, engine event rendering) is routed to stderr so stdout carries only the envelope.

When --output is unset, the format is auto-detected from the terminal: an interactive TTY gets pretty, a piped or redirected stdout gets json. This makes builder ... | jq and CI invocations machine-readable without any extra flags.

builder init additionally accepts a local --json boolean flag selecting the same NDJSON output, and combines with --dry-run for a full structured plan of every operation without writing anything (see the dry-run guide).

Flag placement with builder execute

builder execute treats every token after the <collection>:<schematic> positional argument as a raw schematic flag. Place --output, --theme, and --verbose before the positional:

# Correct — --output is a CLI flag
builder --output=json execute default:my-component --name=button

# Here --output=./dist is passed through to the schematic, NOT to the CLI
builder execute default:my-component --output=./dist

Verbosity

--verbose (global, text mode only) prints full diagnostic output — sanitised — for subprocess and engine failures, and enables debug-level log lines. Several error remedies suggest re-running with --verbose to see the full subprocess output (for example after a package-manager install failure or a codegen failure). JSON output is unaffected by --verbose.

Theming

Pretty output is rendered through an 8-token semantic color palette with light and dark variants. Appearance resolves via a three-level precedence chain:

--theme flag  >  BUILDER_THEME env  >  auto-detect

Precedence	Source	Values
Highest	--theme flag	light, dark, auto (default)
Middle	BUILDER_THEME environment variable	light, dark
Lowest	Auto-detection	Queries the terminal’s background color

# Force light via environment variable
BUILDER_THEME=light builder info

# Flag wins over env (appearance = light)
BUILDER_THEME=dark builder --theme=light info

Auto-detection is lazy: an explicit --theme or BUILDER_THEME skips it entirely. In unusual PTY automation setups the background-color query can stall startup for up to 5 seconds before falling back — set BUILDER_THEME to bypass detection. When stdout is piped or the terminal reports no color support, output degrades gracefully to plain text.

Error contract

Every error the CLI emits includes:

• a stable, machine-readable code (e.g. init_config_exists),
• a human-readable message, and
• a non-empty suggestions list — Fix: entries are direct remedies, Note: entries are context.

Some codes also carry a reason that distinguishes variants of the same code, and a short, path-free detail (for example which field failed). Both appear in JSON output; the tables below list the reason where it changes the remedy.

In text mode, errors render as a fixed block on stderr, independent of where stdout is redirected. In JSON mode, builder execute writes a structured JSON error envelope to stdout instead (and the text block is suppressed), so machine consumers always find the error in the stream they are parsing.

Interactive prompts for sensitive schematic inputs are refused outside a TTY (engine_non_tty_ask_unavailable) — in scripts and CI, pass the value explicitly with builder execute <collection>:<schematic> --<name>=<value>.

Exit codes

Every terminating error resolves to exactly one exit family:

Code	Family	Meaning
0	success	No error.
1	internal	Fail-closed — unclassifiable cause, *_not_implemented codes, and every code not otherwise assigned.
2	usage	CLI input/flag/argument/workspace-state validation.
3	config	The project’s own declared configuration is missing, corrupt, or escaping the workspace.
4	sdk	SDK layer failure (@pbuilder/sdk missing or version mismatch).
5	engine	Engine layer failure.
130	cancelled	SIGINT (Ctrl-C), following the shell convention 128+2.

The family is derived from the outermost CLI error in the chain — never from a wrapped subprocess’s own exit code.

Error code reference

Complete registry of error codes, grouped by area. Where one code covers several distinct situations, each variant message gets its own row.

General

Code	Exit	Message	Remedy
cancelled	130	run cancelled	Note: re-run the command to try again
cli_prompt_failed	1	could not read your answer from the terminal	Fix: re-run in an interactive terminal, or pass the value with --<name>=<value>
cli_unknown_flag	2	unrecognised command-line flag	Fix: run --help to see the accepted flags
invalid_input	2	input value invalid	Note: check the input value against its expected format
not_implemented	1	command not yet implemented	Note: this command is not implemented yet
collection_manifest_invalid	3	collection manifest not found	Fix: check that collection.json exists at the registered path
collection_manifest_invalid	3	collection manifest unparseable	Note: edit collection.json to fix the JSON syntax error

builder init

Code	Exit	Message	Remedy
init_agent_file_ambiguous	2	both AGENTS.md and CLAUDE.md already contain the pbuilder skill marker — ambiguous which file to update	Fix: run with --force to refresh the marker block in both files; or remove the marker from one file manually and re-run
init_config_exists	2	project-builder.json already exists	Fix: run with --force to safely upgrade — existing collections, dependencies, and settings are preserved; or remove project-builder.json manually and re-run
init_dir_not_empty	2	target directory is not empty	Fix: run with --force to initialise anyway
init_install_failed	3	package manager install failed	Fix: use --no-install to skip the install step and run it manually later; or re-run with --verbose to see the full subprocess output
init_marker_corrupt	3	the pbuilder skill marker block in the agent file is malformed	Fix: close the block with <!-- pbuilder:skill:end -->, remove duplicate or orphaned marker lines, then re-run
init_not_implemented	1	init mode not yet implemented	Note: this init mode is not implemented yet
init_package_manager_not_found	3	package manager not found	Fix: run with --package-manager to select one explicitly
init_skill_exists	2	skill artefact set already exists (.claude/skills/pbuilder/)	Fix: run with --force to overwrite the full skill artefact set
invalid_input	2	package.json is not valid JSON	Fix: fix the syntax errors in package.json and re-run
invalid_input	2	package.json <field> field is not a valid string map	Note: fix the devDependencies or scripts field (for example a null value) and re-run. See package.json edits

A failed init leaves the outputs written before the failure on disk. Once fixed, re-run with --force.

builder new

Code	Exit	Message	Remedy
new_codegen_failed	4	@pbuilder/sdk installation could not be resolved for code generation	Fix: reinstall the SDK: bun add -d @pbuilder/sdk; or re-run with --verbose to see the full subprocess output
new_codegen_failed	4	pbuilder-codegen failed	Fix: re-run with --verbose to see the codegen output. If it reports refusing symbolic-link output, reinstalling does not help — see Symbolic-link outputs
new_collection_exists	2	collection already exists	Fix: run with --force to overwrite
new_invalid_extends	2	--extends value does not match the required grammar	Note: --extends must be in the form @scope/pkg:collection
new_invalid_language	2	--language value is not supported	Note: --language accepts ts or js
new_invalid_name	2	schematic name is invalid	Note: names may not contain path separators, shell metacharacters, or null bytes
new_mode_conflict	2	incompatible flags combined	Note: --inline, --force, and --publishable cannot be combined in this way
new_node_not_found	3	no Node.js binary found	Fix: install Node.js >= 18 and ensure it is on PATH, or set NODE_BINARY
new_not_implemented	1	new mode not yet implemented	Note: this new mode is not implemented yet
new_schematic_exists	2	schematic already exists	Fix: run with --force to overwrite

builder execute

Code	Exit	Message	Remedy
execute_ambiguous_registration	2	registration is ambiguous	Note: resolve the collection or schematic to a single registration mode
execute_collection_not_found	2	collection not found in project-builder.json	Note: check project-builder.json for the registered collection name
execute_commit_mode_unsupported	2	commit mode is not supported	Fix: use --commit=never or --commit=always (or --dry-run for never)
execute_invalid_factory_pointer	2	schematic’s factory pointer does not parse	Note: edit collection.json’s factory to <module>#<export>
execute_invalid_factory_pointer	2	schematic has both factory.ts and factory.js — ambiguous	Note: remove factory.ts or factory.js so only one remains
execute_invalid_factory_pointer	2	schematic is missing a factory.ts or factory.js file	Note: create factory.ts or factory.js in the schematic root
execute_invalid_factory_pointer	2	schematic’s factory pointer is empty or missing in collection.json	Note: set collection.json’s factory to <module>#<export>
execute_invalid_input_value	2	input value is invalid	Note: check the input’s type, enum values, and whether it is scalar-typed
execute_manifest_path_escape	3	manifest-derived path resolves outside the workspace root	Note: check the manifest for a path that escapes the project workspace. If sdk.root was removed — or --sdk-root / BUILDER_SDK_ROOT is no longer set — node_modules/@pbuilder/sdk may be a leftover link — confirm it is a symlink, never a directory, then delete it
execute_manifest_path_escape (path_escapes_manifest_root)	3	manifest-derived path resolves outside the named manifest root	Note: check the manifest for a path that escapes the named manifest root
execute_manifest_path_escape (sdk_node_modules_escapes_workspace)	3	node_modules is a symlink that resolves outside the workspace root	Note: check whether node_modules is a symlink pointing outside the project workspace; the leftover sdk.root link note above also applies
execute_missing_required_inputs	2	missing required input(s)	Fix: builder execute <collection>:<schematic> --<name>=<value>
execute_project_not_initialized	3	project-builder.json not found	Fix: run builder init to create project-builder.json; or re-run with --manifest (or BUILDER_MANIFEST) naming a directory that already has one
execute_project_not_initialized	3	project-builder.json exists but could not be parsed	Note: edit project-builder.json to fix the JSON syntax error
execute_schema_invalid	3	schema.json is present but could not be parsed	Note: edit schema.json to fix the JSON syntax error
execute_schematic_not_found	2	schematic not found in collection	Note: check the collection’s manifest for the registered schematic name
execute_sdk_link_failed	4	varies by reason	See SDK diagnostics
execute_sdk_link_path_conflict	4	varies by reason	See SDK diagnostics
execute_sdk_not_installed	4	varies by reason	See SDK diagnostics
execute_sdk_root_invalid	4	varies by reason	See SDK diagnostics
execute_sdk_version_mismatch	4	varies by reason	See SDK diagnostics
execute_unsupported_registration	2	schematic is registered in a mode execute does not support	Note: register the schematic as path-mode or collection-mode
execution_failed	5	schematic execution failed	Note: check the schematic’s own output above for the underlying cause

SDK diagnostics

builder execute checks the workspace’s SDK before running anything (see SDK requirement and SDK source). Each reason calls for a different repair — only sdk_absent means the SDK is actually missing.

Local installation

Code	Reason	Exit	Message	Repair
execute_sdk_not_installed	sdk_absent	4	@pbuilder/sdk is not installed in this workspace	Provide a compatible SDK at node_modules/@pbuilder/sdk (see below)
execute_sdk_not_installed	sdk_dist_incomplete	4	local @pbuilder/sdk distribution is incomplete	The package is there but required distribution files are missing — reinstall it
execute_sdk_not_installed	sdk_installation_unreadable	4	local @pbuilder/sdk installation could not be read; check permissions and broken links	Check permissions and dangling symlinks on node_modules/@pbuilder/sdk
execute_sdk_version_mismatch	sdk_requirement_invalid	4	@pbuilder/sdk requirement is invalid; correct the selected declaration or configuration	Fix the value named in detail, for example project-builder.json.sdk.version: expected a numeric version floor
execute_sdk_version_mismatch	sdk_requirement_unreadable	4	@pbuilder/sdk requirement could not be read; check package.json permissions and size	Check that the workspace package.json is readable and not oversized
execute_sdk_version_mismatch	sdk_version_unparseable	4	installed @pbuilder/sdk version is invalid; check the local package.json	Inspect the version in node_modules/@pbuilder/sdk/package.json
execute_sdk_version_mismatch	sdk_version_below_floor	4	installed @pbuilder/sdk version is below the selected requirement; choose a compatible version	Install a version that meets the selected requirement, or correct the requirement

The CLI does not detect your package manager for these errors: its suggestions list one local installation command per manager, and you choose one. They change package.json and may change the lockfile:

Package manager	Command
npm	npm install --save-dev @pbuilder/sdk
pnpm	pnpm add -D @pbuilder/sdk
Yarn	yarn add --dev @pbuilder/sdk
Bun	bun add -D @pbuilder/sdk

Pin a version when you need reproducible installs. The suggestions also offer the alternative of pointing sdk.root at an existing @pbuilder/sdk directory. To provide an SDK without declaring it, see Evaluate without adopting the SDK.

External root

These codes appear only when an external root is named — by --sdk-root, BUILDER_SDK_ROOT or sdk.root in project-builder.json. Their messages say sdk.root whichever of the three named the root. execute_sdk_version_mismatch applies to an external root exactly as to a local install. No message, detail or JSON field ever contains the configured path: locations are reported relative to the root, such as the configured root itself or 2 levels above sdk.root.

Code	Reason	Exit	Message	Repair
execute_sdk_root_invalid	sdk_root_value_invalid	4	sdk.root in project-builder.json must be a non-empty string path	Set "sdk": {"root": "<directory>"} — absolute, or relative to project-builder.json
execute_sdk_root_invalid	sdk_root_unsupported_scheme	4	sdk root is not a supported location — a URL or drive letter is not accepted	Point --sdk-root (or BUILDER_SDK_ROOT) at a local directory. Only these two can hit it
execute_sdk_root_invalid	sdk_root_unresolvable	4	sdk.root does not resolve to a readable directory	Point sdk.root at an existing, readable @pbuilder/sdk package directory
execute_sdk_root_invalid	sdk_root_package_mismatch	4	the directory named by sdk.root is not @pbuilder/sdk	Point it at the package directory whose package.json name is @pbuilder/sdk — not its parent
execute_sdk_root_invalid	sdk_root_dist_incomplete	4	the @pbuilder/sdk distribution at sdk.root is incomplete	Reinstall or rebuild the SDK so dist/bin/pbuilder-runner.js and dist/transport are present
execute_sdk_root_invalid	sdk_root_dependencies_unresolvable	4	the @pbuilder/sdk at sdk.root cannot load its own dependencies	detail names the dependency (for example ts-morph). Point sdk.root at a complete installation, such as the one bun add -g @pbuilder/sdk creates — not a package-manager cache
execute_sdk_root_invalid	sdk_root_writable_by_others	4	sdk.root itself is writable by its group or by any user	chmod go-w the root so only its owner can write to it
execute_sdk_root_invalid	sdk_ancestor_world_writable	4	a directory above sdk.root is writable by any user and is not sticky	detail gives the depth. chmod o-w that directory, or move the SDK under a directory only you can write to
execute_sdk_root_invalid	sdk_root_untrusted_owner	4	sdk.root, or a directory above it, is owned by another user	Move the SDK under a path owned by you or by root
execute_sdk_link_path_conflict	sdk_root_local_install_present	4	a real @pbuilder/sdk is already installed at node_modules/@pbuilder/sdk and differs from the configured SDK root	Delete node_modules/@pbuilder/sdk to use the configured root, or stop configuring one (--sdk-root, BUILDER_SDK_ROOT or sdk.root) to use the installed SDK
execute_sdk_link_path_conflict	sdk_link_path_occupied	4	node_modules/@pbuilder/sdk is a regular file, so the SDK link cannot be created	Delete that file, then re-run
execute_sdk_link_path_conflict	sdk_link_path_dangling	4	node_modules/@pbuilder/sdk is a link to a target that no longer exists	Delete the broken link (confirm it is a symlink, never a directory), then re-run
execute_sdk_link_path_conflict	sdk_link_path_invalid_package	4	node_modules/@pbuilder/sdk is a directory that is not a usable @pbuilder/sdk package	Remove or reinstall node_modules/@pbuilder/sdk, then re-run
execute_sdk_link_path_conflict	sdk_scope_dir_occupied	4	node_modules/@pbuilder is a file or a link, so the SDK link cannot be placed inside it	Replace node_modules/@pbuilder with a real directory, then re-run
execute_sdk_link_path_conflict	sdk_node_modules_not_a_directory	4	node_modules is a regular file, so the SDK link cannot be created	Delete or rename that file so node_modules can be a directory
execute_sdk_link_path_conflict	sdk_node_modules_unresolvable	4	node_modules is a symlink that does not resolve to a directory	Delete or repair the node_modules symlink, then re-run
execute_sdk_link_failed	sdk_link_write_failed	4	the SDK link node_modules/@pbuilder/sdk could not be written	Check write permission on node_modules and node_modules/@pbuilder, then re-run

Warning	Meaning
warn_sdk_root_group_writable	A directory above the root is group-writable, so anyone in that group could replace the SDK. The run continues; the message names the depth and the remedy — chmod g-w that directory, or move the SDK under a directory only you can write to. Global installs under a shared prefix, such as Homebrew’s, commonly trigger it.
warn_sdk_root_ambient	The root came from BUILDER_SDK_ROOT, not from --sdk-root. The message names the variable, never the path — check the variable itself to see which SDK ran.

pbuilder-codegen is not found, or a different version runs

This is not a builder error: it comes from your package runner (npx, bunx) when you regenerate types by hand. Two situations look alike:

Situation	What happens
@pbuilder/sdk is not installed at all	The runner cannot find the binary — install the SDK
The SDK comes from an external root (sdk.root, --sdk-root or BUILDER_SDK_ROOT)	node_modules/@pbuilder/sdk is a link that no package manager installed, so there is no node_modules/.bin/pbuilder-codegen shim. The runner reports the binary as missing even though the SDK works — or, if an SDK is installed globally, npx can silently run that global copy instead, possibly a different version. Recent pnpm versions install before pnpm exec, which writes a lockfile into the project

With an external root, run the script directly — see Type generation with sdk.root. builder new schematic does not need the shim: it regenerates types from sdk.root by itself.

Manifest root

Errors and warnings from --manifest / BUILDER_MANIFEST. Locations in detail are relative to the manifest root, such as 2 levels above the manifest root.

Code	Reason	Exit	Message	Remedy
manifest_root_unsupported_scheme	manifest_root_unsupported_scheme	2	manifest root is not a supported location — a URL or drive letter is not accepted	Point --manifest (or BUILDER_MANIFEST) at a local directory or project-builder.json file
manifest_root_unresolvable	manifest_root_unresolvable	3	manifest root does not resolve to a usable directory or project-builder.json file	Point it at an existing, readable directory or project-builder.json file
manifest_root_untrusted	manifest_root_untrusted_owner	3	the manifest root is owned by another user	Move the manifest root under a path owned by you or by root
manifest_root_untrusted	manifest_root_writable_by_others	3	the manifest root itself is writable by its group or by any user	chmod go-w the manifest root so only its owner can write to it
manifest_root_untrusted	manifest_root_ancestor_world_writable	3	a directory above the manifest root is writable by its group, or by any user without the sticky bit	chmod o-w (or g-w) that directory, or move the manifest root under a directory only you can write to. A root under /tmp hits this
manifest_root_untrusted	manifest_root_is_filesystem_root	3	the filesystem root cannot be named as a manifest root	Point it at the specific directory holding project-builder.json
manifest_root_untrusted	manifest_root_is_home_directory	3	your home directory cannot be named as a manifest root	Point it at a directory inside your home directory, not the home directory itself
manifest_root_unsupported_command	manifest_root_command_unsupported	2	this command does not support –manifest	--manifest is supported on execute, info and new schematic only
manifest_scoped_authoring_refused	manifest_scoped_authoring_refused	2	new schematic refuses to author under a named external manifest root	cd into that directory and run builder new schematic there instead
collection_absolute_path	collection_path_absolute	3	a manifest-registered path must be relative to the manifest’s own root	Make the registered path relative to the manifest root

Warning	Meaning
warn_manifest_root_ambient	The manifest root came from BUILDER_MANIFEST, not from a flag. The message names the resolved directory.
warn_manifest_sdk_root_ignored	The external manifest declares an sdk.root; it is ignored. The message says the working directory’s installed @pbuilder/sdk was used, but --sdk-root or BUILDER_SDK_ROOT still supply the SDK when set.

A run that fails with engine_native_developer_fault and a note about a split module graph while using --manifest means the manifest root, or a directory above it, has its own @pbuilder/sdk. See External collections.

builder info

Code	Exit	Message	Remedy
info_ambiguous_registration	2	registration is ambiguous	Note: resolve the collection to a single registration mode
info_collection_not_found	2	collection not found in project-builder.json	Note: check project-builder.json for the registered collection name
info_invalid_factory_pointer	3	schematic’s factory pointer is empty or missing	Note: edit collection.json’s factory to <module>#<export>
info_invalid_factory_pointer (path_escapes_manifest_root)	3	schematic’s registered path, factory module, or schema.json resolves outside the named manifest root	Note: keep every registered path inside the manifest root
info_manifest_invalid	3	collection manifest not found	Fix: check that collection.json exists at the registered path
info_manifest_invalid	3	collection manifest could not be parsed	Note: edit collection.json to fix the JSON syntax error
info_project_not_initialized	3	project-builder.json not found	Fix: run builder init to create project-builder.json; or re-run with --manifest (or BUILDER_MANIFEST) naming a directory that already has one
info_project_not_initialized	3	project-builder.json exists but could not be parsed	Note: edit project-builder.json to fix the JSON syntax error
info_schema_invalid	3	schema.json is missing or could not be parsed	Note: ensure schema.json exists at the schematic root and is valid JSON
info_schematic_not_found	2	schematic not found in collection	Note: check the collection’s manifest for the registered schematic name

Engine

Code	Exit	Message	Remedy
engine_non_tty_ask_unavailable	2	sensitive input requires an interactive session	Fix: run in an interactive terminal, or provide it via builder execute <collection>:<schematic> --<name>=<value>
engine_not_found	5	schematics engine binary not found	Fix: install the Angular Schematics CLI: npm install -g @angular-devkit/schematics-cli
engine_version_mismatch	5	schematics engine version below the required floor	Fix: upgrade @angular-devkit/schematics-cli to the required version
engine_native_commit_mode_unsupported	5	the native engine adapter does not support dry-run yet	Note: only CommitMode: always is supported today
engine_native_developer_fault	5	native engine execution failed due to a developer-facing fault in the schematic or its inputs	Note: check the schematic’s file writes and inputs for the underlying cause
engine_native_invalid_factory_url	5	factory URL is empty or malformed	Note: this indicates an internal wiring defect in factory-pointer resolution
engine_native_invalid_plan	5	execute request has no pre-flight plan	Note: this indicates an internal wiring defect — pre-flight must run before the native engine adapter
engine_native_invalid_sdk_anchor	5	execute plan has no resolved SDK location	Note: this indicates an internal wiring defect — pre-flight must run before the native engine adapter
engine_native_provisioning_failed	5	the native engine’s runtime could not be provisioned	Note: check network access, disk space, and binary verification for the native engine’s runtime
engine_native_system_fault	5	native engine system fault	Note: this indicates an engine-side system failure — re-run and report if it persists
engine_native_workspace_inconsistent	5	the workspace may be partially written and is in an inconsistent state	Note: inspect the workspace manually before re-running this operation
engine_spurious_cancellation	5	engine reported a cancellation with no genuine signal behind it	Note: this indicates an engine-side defect — re-run and report if it persists
engine_stream_ended_without_terminal	5	engine event stream ended without a terminal event	Note: this indicates an engine-side defect — re-run and report if it persists