pcl CLI Reference - Phylax Credible Layer Documentation

pcl is the Credible CLI for building, testing, verifying, deploying, and downloading Credible Layer assertions.

New to pcl? Start with the Quickstart Tutorial to learn the workflow.

Version

This reference matches pcl 1.8.0.

pcl 1.8.0
Commit: f7ae8817db2f
Build Timestamp: 2026-08-03T23:19:40Z

Syntax

pcl [OPTIONS] COMMAND

Global Options

Option	Description
`-j, --json`	Emit strict JSON output for programmatic consumers
`--llms`	Print the CLI-native LLM usage guide and exit
`-h, --help`	Print help
`-V, --version`	Print version

Assertion Development Commands

The commands below cover the assertion development workflow documented on this page. Run pcl --help for the complete command list for your installed version.

Command	Description
`pcl test`	Run tests using Phorge
`pcl apply`	Preview and apply declarative deployment changes from `credible.toml`
`pcl deploy`	Create or resolve a project, create a release, and activate it on-chain
`pcl auth`	Authenticate the CLI with your Credible Layer Platform account
`pcl config`	Manage CLI configuration
`pcl build`	Build contracts using Phorge
`pcl verify`	Verify assertions locally before deployment
`pcl download`	Download assertion source code for a protocol

`test`

Runs tests using Phorge.

pcl test [OPTIONS] [PATH]

[PATH] is the contract file to test. It is a shortcut for --match-path.

Common `test` Options

Option	Description
`-v, --verbosity...`	Increase log verbosity. Pass multiple times, such as `-vvv`
`-q, --quiet`	Do not print log messages
`--json`	Format log messages as JSON
`--md`	Format log messages as Markdown
`--color COLOR`	Set log color mode: `auto`, `always`, or `never`
`-s, --suppress-successful-traces`	Show traces only for failures
`--junit`	Output test results as a JUnit XML report
`-l, --list`	List tests instead of running them
`--summary`	Print a test summary table
`--detailed`	Print a detailed test summary table
`--gas-report`	Print a gas report
`--fail-fast`	Stop after the first failure
`--rerun`	Re-run recorded failures from the last run
`-w, --watch [PATH...]`	Watch files or directories for changes

Test Filtering

Option	Description
`--match-test REGEX`	Only run test functions matching the regex
`--no-match-test REGEX`	Exclude test functions matching the regex
`--match-contract REGEX`	Only run tests in matching contracts
`--no-match-contract REGEX`	Exclude tests in matching contracts
`--match-path GLOB`	Only run tests in matching source files
`--no-match-path GLOB`	Exclude tests in matching source files
`--no-match-coverage REGEX`	Exclude matching files from coverage output

EVM and Build Options

pcl test supports many Forge-compatible EVM, fork, compiler, linker, cache, project, and watch options. Use pcl test --help for the complete option list.

pcl test uses Phorge for test execution. Some Forge options may differ from upstream Foundry behavior. Use pcl test --help as the authoritative option list for your installed pcl version.

`apply`

Previews and applies declarative deployment changes from credible.toml.

pcl apply [OPTIONS]

pcl apply reads credible.toml, builds and verifies referenced assertion contracts, previews release changes against the platform, and creates a release after confirmation.

`apply` Options

Option	Description
`--root ROOT`	Project root directory. Default: `.`
`-c, --config CONFIG`	Path to `credible.toml`, relative to root or absolute. Default: `assertions/credible.toml`
`--json`	Emit machine-readable output for this command
`--yes`	Apply without interactive confirmation
`--auto-approve`	Alias for `--yes`
`--dry-run`	Build and verify the release payload without calling the platform API
`-u, --api-url API_URL`	Base URL for the platform API. Uses `PCL_API_URL` when set; otherwise, uses the platform remembered from the last login or network selection
`-h, --help`	Print help

`apply` Behavior

If project_id is omitted from credible.toml, pcl apply prompts you to select a project interactively.
If JSON output is enabled, project_id is required in credible.toml.
If there are no release changes, the command exits without creating a release.
If --yes is omitted, the command prompts for confirmation before applying changes.

`apply` Examples

pcl apply
pcl apply --root ./my-project
pcl apply --root ./my-project -c path/to/credible.toml
pcl apply --yes
pcl apply --json --yes

`deploy`

Creates or resolves a platform project, verifies or sets its protocol manager, creates a release, activates the release on-chain, and confirms the deployment.

pcl deploy [OPTIONS]

`deploy` Options

Option	Description
`--root ROOT`	Project root directory. Default: `.`
`-c, --config CONFIG`	Path to `credible.toml`, relative to root or absolute. Default: `assertions/credible.toml`
`--yes`, `--auto-approve`	Proceed without interactive confirmations
`--dry-run`	Build and verify locally, report which steps would act, and make no changes
`-u, --api-url API_URL`	Base URL for the platform API. Uses `PCL_API_URL` when set; otherwise, uses the platform remembered from the last login or network selection
`--private-key PRIVATE_KEY`	Hex-encoded private key used to sign transactions and challenges. Can also be set with `PCL_PRIVATE_KEY`
`--account ACCOUNT`	Foundry keystore name from `~/.foundry/keystores`
`--keystore-password KEYSTORE_PASSWORD`	Foundry keystore password. Can also be set with `PCL_KEYSTORE_PASSWORD`
`--keystore-password-file PATH`	File containing the Foundry keystore password. Can also be set with `PCL_KEYSTORE_PASSWORD_FILE`
`--rpc-url RPC_URL`	RPC endpoint used to broadcast transactions. Can also be set with `PCL_RPC_URL`
`--confirmations CONFIRMATIONS`	Confirmations to wait for after broadcasting. Values below the platform requirement are rejected
`--tx-timeout-secs SECONDS`	Transaction confirmation timeout. Default: `300`
`--project-name PROJECT_NAME`	Project name used when `credible.toml` has no `project_id`; overrides `project_name` in the file
`--chain-id CHAIN_ID`	Chain ID used when creating a project. Existing project chains are read from the platform
`--skip-protocol-manager`	Skip protocol-manager verification or configuration
`--check-timeout-secs SECONDS`	Timeout for deployment-blocking release checks. Default: `600`
`-j, --json`	Emit strict JSON output
`--llms`	Print the CLI-native LLM usage guide and exit
`-h, --help`	Print help

`deploy` Behavior

--dry-run returns after building and verifying the local release payload. It does not authenticate, resolve a project, validate a chain, or inspect the protocol manager.
Without --dry-run, the command requires authentication, project information, an RPC endpoint, and a signer unless the relevant step is already complete or explicitly skipped.
If credible.toml has no project_id, provide a project name and chain ID so the command can create the project.
Existing projects use the chain recorded by the platform.
If --yes is omitted, the command requests confirmation before mutations and broadcasts.
The command observes existing state before each step so an interrupted workflow can resume.

`deploy` Examples

pcl deploy --dry-run
pcl deploy --account protocol-manager --rpc-url https://example-rpc.invalid
pcl deploy --project-name my-protocol --chain-id 84532 --account protocol-manager --rpc-url https://example-rpc.invalid --yes --json

`auth`

Authenticates the CLI with your Credible Layer Platform account.

pcl auth [OPTIONS] COMMAND

`auth` Commands

Command	Description
`ensure`	Confirm that authentication is usable or return a login challenge
`login`	Login to PCL
`poll`	Poll a pending device-login session once
`refresh`	Refresh authentication or return a login challenge
`logout`	Logout from PCL
`status`	Check current authentication status
`help`	Print help

`auth` Options

Option	Description
`-u, --auth-url AUTH_URL`	Base URL for authentication. Resolution order: `PCL_AUTH_URL`, `PCL_API_URL`, the URL remembered from the last login, then `https://app.phylax.systems`
`-h, --help`	Print help

pcl auth login displays a device code, then opens a browser after you press Enter. Use --no-wait with --json to return the login challenge without waiting for verification.

`config`

Manages CLI configuration.

pcl config COMMAND

`config` Commands

Command	Description
`show`	Display the current configuration
`delete`	Delete the current configuration
`set-rpc CHAIN_ID URL`	Store the RPC endpoint used to broadcast transactions on a chain
`unset-rpc CHAIN_ID`	Remove the stored RPC endpoint for a chain
`help`	Print help

Configuration is stored in ~/.config/pcl/config.toml by default and includes authentication state, the remembered platform URL, and per-chain RPC settings.

`build`

Builds contracts using Phorge.

pcl build [OPTIONS]

`build` Options

Option	Description
`--root ROOT`	Root directory of the project
`-h, --help`	Print help

`verify`

Verifies assertions locally before deployment.

pcl verify [OPTIONS] [ASSERTION]

[ASSERTION] can be a contract name or file:contract. If omitted, pcl verify verifies all assertions from credible.toml.

`verify` Options

Option	Description
`--root ROOT`	Project root directory. Default: `.`
`-c, --config CONFIG`	Path to `credible.toml`, relative to root or absolute. Default: `assertions/credible.toml`
`--args ARGS...`	Constructor arguments for the assertion
`--json`	Emit machine-readable JSON output
`-h, --help`	Print help

`verify` Behavior

When [ASSERTION] is omitted, constructor arguments come from each assertion’s args field in credible.toml.
--args can only be used when verifying a specific assertion.
Constructor arguments are ABI-encoded against the assertion contract constructor.
The command exits with code 1 if any assertion fails verification.

Verification Statuses

Status	Meaning
`success`	The assertion verified successfully
`deployment_failure`	The assertion failed during deployment in the local verification environment
`no_triggers`	The assertion did not expose any triggers
`missing_assertion_spec`	The assertion is missing the required assertion specification
`invalid_assertion_spec`	The assertion specification is invalid

`verify` Examples

pcl verify
pcl verify OwnableAssertion
pcl verify assertions/src/OwnableAssertion.a.sol:OwnableAssertion
pcl verify OwnableAssertion --args 0x75634113D6A2fbfF5e65151ce1572195bE1d001A
pcl verify --json

`download`

Downloads assertion source code for a protocol.

pcl download [OPTIONS]

`download` Options

Option	Description
`--project-id PROJECT_ID`	Project UUID to download assertions from
`-o, --output-dir OUTPUT_DIR`	Output directory for `.sol` files. Default: `PROJECT_NAME-assertions/`
`--json`	Emit machine-readable output for this command
`-u, --api-url API_URL`	Base URL for the platform API. Uses `PCL_API_URL` when set; otherwise, uses the platform remembered from the last login or network selection
`-h, --help`	Print help

`download` Behavior

--project-id is required.
The command requires authentication. Run pcl auth login first.
By default, files are written to a directory named after the project: PROJECT_NAME-assertions/.
Downloaded files use the pattern CONTRACT_NAME_ASSERTION_ID_PREFIX.sol.
Assertions without available source are skipped.

`download` Examples

pcl download --project-id 550e8400-e29b-41d4-a716-446655440000
pcl download --project-id 550e8400-e29b-41d4-a716-446655440000 -o ./downloaded-assertions
pcl download --project-id 550e8400-e29b-41d4-a716-446655440000 --json

`credible.toml` Configuration

The credible.toml file defines assertion deployment configuration for pcl apply and pcl verify. Default location: assertions/credible.toml, relative to the project root.

Format

environment = "production"
project_id = "550e8400-e29b-41d4-a716-446655440000"

[contracts.my_contract]
address = "0x1234567890abcdef1234567890abcdef12345678"
name = "MyContract"

[[contracts.my_contract.assertions]]
file = "assertions/src/MyAssertion.a.sol"
args = ["0x75634113D6A2fbfF5e65151ce1572195bE1d001A", "42"]

Root Fields

Field	Type	Required	Description
`environment`	string	Yes	Deployment environment name, such as `"production"`
`project_id`	UUID	No	Platform project ID. Required when `pcl apply` emits JSON output
`contracts`	map	Yes	Named contract definitions

Contract Fields

Field	Type	Required	Description
`address`	string	Yes	Contract address on-chain
`name`	string	Yes	Human-readable contract name
`assertions`	array	Yes	Assertions to apply to this contract

Assertion Fields

Field	Type	Required	Description
`file`	string	Yes	Assertion contract file path. Use `file.sol:ContractName` when the contract name cannot be inferred from the filename
`args`	array or scalar	No	Constructor arguments for the assertion. Values are converted to strings before ABI encoding

Contract Name Inference

pcl infers assertion contract names from file in this order:

`file` value	Inferred contract
`assertions/src/MyAssertion.a.sol:ExplicitAssertion`	`ExplicitAssertion`
`assertions/src/MyAssertion.a.sol`	`MyAssertion`
`assertions/src/MyAssertion.sol`	`MyAssertion`

Validation

Contract addresses must be unique within the file.
pcl verify returns an error if credible.toml contains no assertions.
pcl apply --json returns an error if project_id is missing.

Environment Variables

Variable	Used by	Description	Default
`PCL_AUTH_URL`	`pcl auth`	Base URL for the authentication service	`PCL_API_URL`, then the remembered login URL, then `https://app.phylax.systems`
`PCL_API_URL`	Platform API commands	Base URL for the platform API	Platform remembered from the last login or network selection

Configuration File

pcl stores CLI configuration in ~/.config/pcl/config.toml by default. Use pcl config show to view the current configuration and pcl config delete to delete it.

Next Steps

Apply Assertions

Learn how to create an assertion release with pcl apply

Quick Start Guide

Step-by-step tutorial for your first assertion

Installation

Install pcl

Deploy with the Platform

Deploy assertions to protect your contracts

​Version

​Syntax

​Global Options

​Assertion Development Commands

​test

​Common test Options

​Test Filtering

​EVM and Build Options

​apply

​apply Options

​apply Behavior

​apply Examples

​deploy

​deploy Options

​deploy Behavior

​deploy Examples

​auth

​auth Commands

​auth Options

​config

​config Commands

​build

​build Options

​verify

​verify Options

​verify Behavior

​Verification Statuses

​verify Examples

​download

​download Options

​download Behavior

​download Examples

​credible.toml Configuration

​Format

​Root Fields

​Contract Fields

​Assertion Fields

​Contract Name Inference

​Validation

​Environment Variables

​Configuration File

​Next Steps

Apply Assertions

Quick Start Guide

Installation

Deploy with the Platform

Version

Syntax

Global Options

Assertion Development Commands

`test`

Common `test` Options

Test Filtering

EVM and Build Options

`apply`

`apply` Options

`apply` Behavior

`apply` Examples

`deploy`

`deploy` Options

`deploy` Behavior

`deploy` Examples

`auth`

`auth` Commands

`auth` Options

`config`

`config` Commands

`build`

`build` Options

`verify`

`verify` Options

`verify` Behavior

Verification Statuses

`verify` Examples

`download`

`download` Options

`download` Behavior

`download` Examples

`credible.toml` Configuration

Format

Root Fields

Contract Fields

Assertion Fields

Contract Name Inference

Validation

Environment Variables

Configuration File

Next Steps