CLI Tooling
Relevant source files
The following files were used as context for generating this wiki page:
The Pop Lang project utilizes a unified command-line interface (CLI) strategy centered around the pop command, which serves as the primary entry point for developers. This tooling is designed to be coherent, providing consistent diagnostics, configuration, and machine-readable protocols across the entire development lifecycle, from project initialization to deployment.
The CLI is architected to interface with the project's canonical code hierarchy: Workspace → Package → Bubble → Module → Item. By providing a single toolchain, Pop Lang ensures that common tasks such as building, testing, and formatting are standardized, reducing the friction typically associated with multi-tool environments.
Sources: architecture/21-cli-tooling-and-code-units.md:1-12, architecture/decisions/0017-bubbles-packages-workspaces-and-cli.md:20-22, AGENTS.md:280-285
Tooling Architecture and Commands
The CLI architecture is built on a query-based API shared among the CLI, language server (LSP), and other development tools. This ensures that all tools consume the same semantic facts and produce identical diagnostics.
Primary Command Suite
The pop command includes a set of core subcommands that manage the lifecycle of Pop Lang projects.
| Command | Purpose |
|---|---|
pop check | Resolves and type-checks code through HIR/MIR verification without native linking. |
pop build | Compiles selected Bubbles and their dependencies. |
pop run | Builds and executes exactly one binary or example Bubble. |
pop test | Executes unit, integration, and XML documentation tests. |
pop format | Applies or verifies the project's canonical whitespace and layout rules. |
pop documentation | Validates XML documentation and generates artifacts for public Bubbles. |
pop add / pop remove | Transactionally modifies dependencies in bubble.toml and updates bubble.lock. |
pop metadata | Outputs the resolved project graph as versioned JSON for machine consumption. |
Sources: architecture/21-cli-tooling-and-code-units.md:188-210, architecture/decisions/0017-bubbles-packages-workspaces-and-cli.md:14-22
Toolchain Management with popup
A specialized manager named popup handles the distribution and installation of the toolchain itself. This separation prevents pop from needing to self-update and manages multiple versions of the compiler and runtime.
The popup tool is responsible for verifying signed release metadata and ensuring the integrity of the toolchain through SHA-256 digests.
Sources: architecture/decisions/0028-toolchain-distribution-and-popup-management.md:32-55, architecture/decisions/0028-toolchain-distribution-and-popup-management.md:175-185
Workspace and Package Management
Tooling operations are governed by the location of bubble.toml and bubble.lock files. The CLI identifies the nearest ancestor bubble.toml with a [workspace] section to determine the root of the project.
Dependency Resolution Flow
The following diagram illustrates how the CLI resolves dependencies when a command like pop build is executed.
Selection Controls
The CLI provides explicit flags to control the scope of operations within a multi-package workspace.
| Flag | Description |
|---|---|
--workspace | Operates on all packages defined in the workspace. |
--package <name> | Limits the command to a specific package. |
--bubble <name> | Targets a specific compilation unit (Bubble). |
--locked | Rejects any command that would modify bubble.lock. |
--frozen | Equivalent to --locked --offline, ensuring complete reproducibility. |
Sources: architecture/21-cli-tooling-and-code-units.md:214-229, architecture/decisions/0017-bubbles-packages-workspaces-and-cli.md:30-35
Machine Protocols and Diagnostics
A critical design principle of Pop Lang tooling is that machine consumers must not "scrape" human-readable output. Instead, the CLI emits versioned, structured data.
- JSON Output: Commands support
--messageFormat jsonto provide stable schemas for errors, progress events, and metadata. - Structured Diagnostics: Errors include stable
POP####codes, typed arguments, and precise source spans. - Debug Dumps: For compiler bootstrap and debugging,
pop checksupports dumping Intermediate Representations (IR):--dump hir: High-level IR after verification.--dump mir: Canonical Mid-level IR.--dump ll: Textual LLVM IR after backend lowering.
Sources: architecture/21-cli-tooling-and-code-units.md:231-255, architecture/decisions/0017-bubbles-packages-workspaces-and-cli.md:24-30, AGENTS.md:288-290
Standalone Module Inspection
For rapid prototyping or compiler testing, the CLI allows checking a single .pop file without a full package structure. In this mode, the driver creates an ephemeral workspace and bubble context to maintain the internal ownership invariants of the language.
Standalone mode is restricted: it cannot declare dependencies, exercise cross-module visibility, or populate the workspace cache.
Sources: architecture/decisions/0017-bubbles-packages-workspaces-and-cli.md:24-29, architecture/21-cli-tooling-and-code-units.md:231-236
Summary
Pop Lang CLI tooling provides a robust, unified environment for managing native, statically typed code. By strictly enforcing a hierarchy of Workspace, Package, and Bubble, the pop and popup tools ensure that dependencies are deterministic, builds are reproducible, and machine integrations are reliable through structured protocols rather than human text parsing.
Sources: architecture/21-cli-tooling-and-code-units.md:290-305, architecture/decisions/0028-toolchain-distribution-and-popup-management.md:12-25