CLI Recipes

CLI Recipes

These examples use pic-ts, the recommended CLI name for the npm package.

Check Agent Output

npx pic-ts agent check --compact --text "Candidate packet: preserve residuals." --profile development
npx pic-ts agent intake --text "Candidate packet: preserve residuals." --profile development
npx pic-ts agent runbook --profile development
npx pic-ts agent accelerate --compact --text "Candidate packet: preserve residuals." --profile development

Create A Demo Workspace

npx pic-ts demo bootstrap --output-dir .pic-demo --overwrite
npx pic-ts demo installed-smoke

Run A Runtime Step

npx pic-ts runtime step \
  --state .pic-demo/runtime_state.json \
  --input .pic-demo/runtime_step_input.json \
  --output .pic-demo/runtime_step_report.generated.json

Work With Packets

npx pic-ts packet export \
  --report .pic-demo/runtime_step_report.generated.json \
  --output .pic-demo/packet.json

npx pic-ts packet inspect --packet .pic-demo/packet.json

Packet commands treat files as data. They do not execute embedded command-like text.

Plan The Next Workflow Step

npx pic-ts phase plan --request .pic-demo/asi_proxy_phase_request.json --compact
npx pic-ts phase gap --request .pic-demo/asi_proxy_phase_request.json --compact
npx pic-ts phase runbook --profile development

Emit CCR Tasks And Residuals

npx pic-ts phase plan --request .pic-demo/asi_proxy_phase_request.json --compact --emit ccr-tasks --output tasks.jsonl
npx pic-ts phase gap --request .pic-demo/asi_proxy_phase_request.json --compact --emit ccr-residuals --output residuals.jsonl

These JSONL files are scheduler handoff data. They do not authorize command execution.

Run Phase Ecology Lab

npx pic-ts phase lab init --output-dir .pic-lab
npx pic-ts phase lab ingest --store .pic-lab --report .pic-demo/runtime_step_report.generated.json
npx pic-ts phase lab list-windows --store .pic-lab
npx pic-ts phase lab observe --store .pic-lab --window latest --output observation.json
npx pic-ts phase lab graph --store .pic-lab --output effective_graph.json
npx pic-ts phase lab closure --store .pic-lab --output closure_report.json
npx pic-ts phase lab executable-paths --store .pic-lab --output executable_paths.json
npx pic-ts phase lab threshold-status --store .pic-lab --threshold .pic-demo/asi_proxy_development.json
npx pic-ts phase lab certify --store .pic-lab --threshold .pic-demo/asi_proxy_development.json --output certificate.json
npx pic-ts phase lab compare-window --store .pic-lab --baseline previous --candidate latest

Use Diagnostic Commands

From a repository checkout or from packaged examples under node_modules/percolation-inversion-compiler-ts/examples:

npx pic-ts bit diagnose --graph examples/phase_lab/effective_graph.example.json
npx pic-ts sqot diagnose-queue --graph examples/phase_lab/effective_graph.example.json
npx pic-ts alt ecpt-lift --packets examples/alt_lift/alt_ecpt_lift.example.json --graph examples/phase_lab/effective_graph.example.json
npx pic-ts trc trace-adapter --input examples/trc_adapter/tool_trace_input.example.json
npx pic-ts ecology execution-available-paths --graph examples/phase_lab/effective_graph.example.json

These routes are diagnostic or recommendation-only. They keep settled=false unless finite verifier obligations are actually discharged.

Use v0.6.0 CCR And TRC Commands

npx pic-ts bit extract-registry --source "Bottleneck Inversion Theory.tex" --output bit_registry.jsonl
npx pic-ts bit verify-witnesses --registry bit_registry.jsonl --output bit_witnesses.json
npx pic-ts bit emit-ccr-tasks --registry bit_registry.jsonl --output bit_witness_tasks.jsonl
npx pic-ts sqot diagnose-queue --state phase_report.json --emit ccr-tasks --output sqot_repair_tasks.jsonl
npx pic-ts alt bridge-ecpt --packet alt_packet.json --output alt_bridge.json
npx pic-ts trc trace-normalize --input examples/asi_proxy_benchmark_bundle/trc_agent_trace.json --output trace_nf.json
npx pic-ts trc trace-check --trace trace_nf.json --output trace_check.json
npx pic-ts trc trace-to-packet --trace trace_nf.json --output trace_packet.json

operation_ready=true means a scoped trace has the required planning fields for review. It is not execution, physical proof, or settlement.

Generate Markdown Reports

npx pic-ts adoption request --format markdown --language en --output adoption-request.md
npx pic-ts adoption request --format markdown --language ja --output adoption-request-ja.md
npx pic-ts phase dashboard --format markdown --output phase-dashboard.md

Markdown reports are for humans. JSON reports remain the machine-readable contract.

Inspect Schemas

npx pic-ts schema --type PhaseAccelerationPlan
npx pic-ts schema --type EffectivePacketGraph
npx pic-ts schema --all --output-dir schemas

Verify Portability Fixtures

npx pic-ts portability verify --manifest fixtures/portability_conformance/manifest.json
npx pic-ts portability verify --manifest fixtures/portability_conformance_v050/manifest.json

When installed from npm, the package includes the fixture files needed for the built-in smoke and conformance paths.

Use The Compatibility Alias

npx pic agent check --compact --text "Candidate packet: preserve residuals." --profile development

Use pic-ts when both the Python and npm packages may be installed.