CLI Recipes

CLI Recipes

This page gives practical command patterns.

Commands that use examples/... assume a source checkout. Commands that use pic-demo/... work after pic demo bootstrap.

Human-facing examples use explicit file names instead of shell wildcards.

Install And Check

python -m pip install percolation-inversion-compiler
pic --version
pic agent explain
pic agent check --compact --text "Candidate packet: preserve residuals." --profile development
pic phase plan --compact --text "Candidate packet: preserve residuals." --profile development
pic agent runbook --profile development

Demo Bootstrap

pic demo installed-smoke --profile development
pic demo bootstrap --output-dir pic-demo
pic runtime step --state pic-demo/runtime_state.json --input pic-demo/runtime_step_input.json --profile development

Phase Ecology Lab

pic phase lab init --output-dir pic-demo/phase-lab
pic phase lab ingest --store pic-demo/phase-lab --report pic-demo/phase_lab_runtime_report.json
pic phase lab list-windows --store pic-demo/phase-lab
pic phase lab observe --store pic-demo/phase-lab --window latest
pic phase lab graph --store pic-demo/phase-lab --output pic-demo/effective_graph.json
pic phase lab closure --store pic-demo/phase-lab
pic phase lab executable-paths --store pic-demo/phase-lab
pic phase lab threshold-status --store pic-demo/phase-lab --threshold pic-demo/phase_lab_threshold.json
pic phase lab certify --store pic-demo/phase-lab --threshold pic-demo/phase_lab_threshold.json
pic phase lab compare-window --store pic-demo/phase-lab --baseline previous --candidate latest
pic phase lab export --store pic-demo/phase-lab --output-dir pic-demo/phase-lab-export

Effective Graph And Paths

uv run pic ecology effective-graph --reports examples/phase_lab/runtime_report_1.json --output effective_graph.json
uv run pic ecology execution-available-paths --graph effective_graph.json
uv run pic phase closure find --graph effective_graph.json
uv run pic phase closure certify --graph effective_graph.json

For multiple reports, repeat the option:

uv run pic ecology effective-graph --reports examples/phase_lab/runtime_report_1.json --reports examples/phase_lab/runtime_report_2.json --output effective_graph.json

BIT: Bottleneck Diagnostics

uv run pic bit diagnose --graph effective_graph.json
uv run pic bit invert --bottlenecks examples/bit_engine/bottlenecks.example.json
uv run pic bit mec --graph effective_graph.json
uv run pic bit certificate --candidate examples/bit_engine/inversion_candidates.example.json
uv run pic bit compare-baseline --baseline examples/bit_engine/bottlenecks.example.json --candidate examples/bit_engine/bottlenecks.example.json

SQOT: Queue Diagnostics

uv run pic sqot diagnose-queue --graph effective_graph.json
uv run pic sqot salience-obstruction --graph effective_graph.json
uv run pic sqot rebalance --graph effective_graph.json
uv run pic sqot quarantine --graph effective_graph.json
uv run pic sqot reserve-check --graph effective_graph.json

ALT Lift

uv run pic alt ecpt-lift --packets examples/packet_exchange/packet_envelope.example.json --graph effective_graph.json
uv run pic alt receiver-lift --packet examples/packet_exchange/packet_envelope.example.json --receiver-context development
uv run pic alt liquidity-to-paths --packet examples/packet_exchange/packet_envelope.example.json --graph effective_graph.json
uv run pic alt capital-impact --reports examples/alt_lift/alt_ecpt_lift.example.json

TRC Trace Adapter

uv run pic trc trace-adapter --input examples/trc_adapter/tool_trace_input.example.json
uv run pic trc tool-trace --events examples/trc_adapter/tool_trace_input.example.json
uv run pic trc action-boundary --report examples/portability_conformance/runtime_step_report.json

Schemas

pic schema --type AgentCheckReport
pic schema --type EffectivePacketGraph
pic schema --type TraceAdapterReport
pic schema --all --output-dir schemas

Live Intake With Explicit Source

PIC can read explicitly supplied web or feed sources when connector support is installed. The output stays candidate-only.

pic ecology ingest-general --source https://example.org --kind web-page
pic ecology ingest-general --source https://example.org/feed.xml --kind rss
pic ecology ingest-general --source https://example.org --kind web-page --no-allow-live-connectors

No background crawling, autonomous polling, form submission, or shell execution is granted by these commands.

Production Identity Context

Production packet promotion requires stronger identity context.

uv run pic identity derive-context --population examples/agent_population_signed.json --profile production --output identity-context.json
uv run pic agent intake --text "Signed packet candidate." --profile production --identity-context identity-context.json

Accepted identity context removes only identity-readiness blockers. It does not settle route, residual, or phase-gap work.