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

CCR Interop JSONL

Use these commands when PIC should hand candidate work to Collective Capability Runtime as inert JSONL.

pic phase plan --compact --emit ccr-tasks --output tasks.jsonl
pic phase gap --compact --emit ccr-residuals --output residuals.jsonl

tasks.jsonl contains ccr.task.v0.1 records. residuals.jsonl contains ccr.residual.v0.1 records. PIC-emitted tasks keep constraints.allowed_commands=[]; command hints are data, not execution grants.

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
uv run pic bit extract-registry --source "Bottleneck Inversion Theory.tex" --output bit_registry.jsonl
uv run pic bit verify-witnesses --registry bit_registry.jsonl --output bit_witnesses.json
uv run pic bit emit-ccr-tasks --registry bit_registry.jsonl --output bit_witness_tasks.jsonl

SQOT: Queue Diagnostics

uv run pic sqot diagnose-queue --graph effective_graph.json
uv run pic sqot diagnose-queue --state phase_report.json --emit ccr-tasks --output sqot_repair_tasks.jsonl
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
uv run pic trc trace-normalize --input examples/asi_proxy_benchmark_bundle/trc_agent_trace.json --output trace_nf.json
uv run pic trc trace-check --trace trace_nf.json --output trace_check.json
uv run pic trc trace-to-packet --trace trace_nf.json --output trace_packet.json

trace-check can report real_world_operation_gate.operation_ready=true only for a scoped candidate with explicit authority, resource, rollback, witness, schedule, and tolerance data. It still reports data; it does not execute the operation.

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.