CLI Recipes

CLI Recipes

This page gives practical command patterns.

Commands that use examples/... assume a source checkout. For installed-package use, prefer inline --text, pic demo bootstrap, pic snapshot, sidecar diagnostics, and your own JSON files.

Explain The Agent Contract

pic agent explain
pic agent guide --profile development

Source checkout:

uv run pic agent explain
uv run pic agent guide --profile development

Run A Minimal Intake

pic agent check --compact --text "Candidate packet: preserve residuals." --profile development
pic phase plan --compact --text "Candidate packet: preserve residuals." --profile development
pic agent accelerate --compact --text "Candidate packet: preserve residuals." --profile development
pic agent runbook --profile development

Source checkout:

uv run pic agent check --compact --text "Candidate packet: route evidence and preserve residuals." --profile development
uv run pic agent intake --text "Candidate packet: route evidence and preserve residuals." --profile development

Save A Report And Ask For Next Steps

uv run pic agent check --compact --text-file examples/agent_minimal/agent_output.txt --profile development --output agent-check-report.json
uv run pic agent intake --text-file examples/agent_minimal/agent_output.txt --profile development --output intake-report.json
uv run pic agent next --intake-report intake-report.json --profile development

Run A Runtime Step

uv run pic runtime step --state examples/runtime_state.json --input examples/runtime_step_input.json --profile production

Check Readiness

uv run pic doctor --profile development --fail-on never
uv run pic doctor --profile production --fail-on never
uv run pic audit canonical-readiness --profile development --format json
uv run pic agent autonomy-audit --profile development --format json

Route-scoped readiness:

uv run pic doctor --profile production --required-route adapters.domain.verify_trc_telemetry_calibration --fail-on never

Inspect Theory Snapshots

uv run pic snapshot list
uv run pic snapshot show --artifact ecpt
uv run pic snapshot show --artifact bit
uv run pic snapshot show --artifact trc
uv run pic snapshot show --artifact sqot
uv run pic snapshot show --artifact alt
uv run pic snapshot routes

Snapshots are derived metadata. They help route checks. They are not independent evidence.

Optional Sidecars

Sidecars are extra reports. They are not required for the core agent path and they do not make settled=true.

pic adoption packet --profile development --format markdown
pic adoption request --profile development --format markdown
pic phase benchmark-suite --profile development --format json
pic phase dashboard --profile development --format json

Japanese Markdown renderers are available for selected handoff reports:

pic adoption packet --profile development --format markdown --language ja
pic agent autonomy-audit --profile development --format markdown --language ja

Packet Exchange

Packet exchange commands treat files as data. They inspect command-like text but never execute it.

pic demo bootstrap --output-dir pic-demo
pic packet inspect --packet pic-demo/packet_envelope.json
pic packet merge --packets pic-demo/packet_envelope.json --output merged-packets.json
pic packet lineage --packet merged-packets.json

Glob patterns are expanded by PIC, so --packets packets/*.json and --reports reports/*.json work consistently across common shells.

Check Identity And Sybil Resistance

uv run pic identity verify --identity examples/identity/agent_identity_alice.json
uv run pic identity sybil-check --population examples/agent_population_signed.json
uv run pic identity derive-context --population examples/agent_population_signed.json --profile production --output identity-context.json

Agent-To-Agent Messages

uv run pic agent relay-readiness --profile development
uv run pic agent message send --inbox inbox.json --sender agent:alice --text "Candidate packet: preserve residuals."
uv run pic agent message receive --inbox inbox.json
uv run pic agent inbox verify --inbox inbox.json
uv run pic agent message create --sender agent:alice --text "Candidate packet: preserve residuals." --output message.json
uv run pic agent message contract --message message.json
uv run pic agent message verify --message message.json --profile development
uv run pic agent message ingest --message examples/agent_network/agent_message.json

Production verification needs accepted identity context.

External Intake

Offline examples:

uv run pic ecology ingest-general --source examples/agent_network/feed.xml --kind rss
uv run pic ecology ingest-general --source examples/agent_network/page.html --kind web-page
uv run pic ecology bridge-runtime --report examples/agent_network/general_intake_report.example.json

Explicit-source live intake is live-capable by default in v0.4.4. It is bounded and candidate-only:

uv run pic ecology ingest-general --source https://example.org --kind web-page
uv run pic ecology ingest-general --source https://example.org/feed.xml --kind rss

Use --no-allow-live-connectors for local-only dry runs:

uv run pic ecology ingest-general --source https://example.org --kind web-page --no-allow-live-connectors

Live intake does not execute page scripts, submit forms, crawl in the background, mutate repositories, or promote packets to settled status.

ALT Abstraction Capital

uv run pic alt certify-liquidity --certificate examples/alt/liquidity_certificate.json
uv run pic alt admit --packet examples/alt/admission_packet.json
uv run pic alt foundry-dashboard --state examples/alt/foundry_state.json
uv run pic alt negative-certify --certificate examples/alt/negative_liquidity_certificate.json

Collective Certificate

uv run pic runtime collective-certify --population examples/agent_population.json --state examples/collective_runtime_state.json --basin examples/ecpt_basin_contract.json --baseline examples/runtime_baseline_run.json --threshold examples/runtime_threshold.json

The result is protocol-relative. It does not prove real ASI.

Portability And Schemas

Use schemas as the cross-language contract for non-Python ports.

pic schema --all --output-dir schemas
pic schema --type AgentAutonomyAuditReport
pic schema --type PacketExchangeEnvelope
pic portability verify --manifest examples/portability_conformance/manifest.json --fail-on never

Source checkout is required for the root examples/portability_conformance tree.