Skip to content

cli.md

Latest commit

 

History

History
342 lines (250 loc) · 13.3 KB

cli.md

File metadata and controls

342 lines (250 loc) · 13.3 KB
Raw

CLI Reference

Executable entrypoint:

  • fullbleed

Python module entrypoints:

  • python -m fullbleed_cli
  • python -m fullbleed (delegates to CLI)

Global flags

  • --json: emit JSON result payloads
  • --json-only: strict machine mode (--json, no prompts)
  • --schema: print schema envelope for the requested command
  • --config
  • --log-level
  • --no-color
  • --no-prompts

Command groups

Core render pipeline:

  • render
  • verify
  • plan
  • run
  • finalize (template composition workflow)
  • inspect (PDF metadata + compatibility inspection)

Diagnostics and introspection:

  • doctor
  • capabilities
  • agent-contract / agent-manifest
  • agent manifest|skill-path|export-skill|install-skill
  • agent-acceptance prepare|verify|run
  • mcp
  • compliance
  • debug-perf
  • debug-jit

Asset/cache:

  • assets list|info|install|verify|lock
  • cache dir|prune

Project generation:

  • init
  • new

Agent runtime truth

fullbleed agent-contract --format json emits fullbleed.agent_contract.v1, the canonical semantic and technical contract generated by the installed runtime. fullbleed agent-manifest --json and fullbleed agent manifest --json are aliases. The contract includes:

  • product identity and installed version;
  • recommendation boundary and workflows;
  • runtime capabilities and supported PDF profiles;
  • parser-derived commands/options and result schemas;
  • supported inputs/outputs, examples, and limitations;
  • the first-party Agent Skill and MCP surface;
  • cold-agent acceptance scenarios.

Other generated views use the same payload:

fullbleed agent-contract --format markdown
fullbleed agent-contract --format llms

The built wheel, not committed prose, is authoritative. Release CI regenerates and checks fullbleed-agent-contract.json, cli_schema.md, and llms.txt from the installed wheel.

The bundled, vendor-neutral Agent Skill can be inspected or safely copied into an absent or empty target:

fullbleed agent skill-path --json
fullbleed agent export-skill .agents/skills/fullbleed --json

fullbleed agent-acceptance prepare|verify|run creates isolated invoice, report, accessible-document, PDF-template, and compiled-VDP tasks for testing unfamiliar agents. See agent_acceptance/README.md for the isolation and judging contract.

fullbleed mcp --root . starts the dependency-free first-party stdio adapter. fullbleed-mcp is the separately distributed discovery wrapper; both entrypoints use the same runtime implementation and workspace path policy.

Core workflow commands

render

Render HTML/CSS to PDF and optionally emit diagnostics/artifacts.

High-value options:

  • input: --html / --html-str, --css, --css-str
  • output: --out
  • assets: --asset, --asset-kind, --asset-name, --asset-trusted
  • template compose (auto-finalize): --template-binding, --templates, --template-dx, --template-dy
  • page/pdf: --page-size, --page-width, --page-height, --margin, --pdf-version, --pdf-profile
  • diagnostics: --emit-jit, --emit-perf, --emit-glyph-report, --emit-page-data, --emit-compose-plan
  • image artifacts: --emit-image, --image-dpi
  • policy: --profile, --fail-on, --allow-fallbacks, budget flags
  • reproducibility: --deterministic-hash, --repro-record, --repro-check
  • development (2.5.0+): --watch, repeatable --watch-path, --watch-interval, --watch-debounce; see automatic rebuilds

Template auto-compose notes:

  • When --templates is set on render, CLI renders overlay, resolves template bindings, and finalizes via Rust compose in one command.
  • Requires --template-binding and file output (--out cannot be -).
  • When --emit-image is used with template auto-compose, image artifacts are emitted from the finalized composed PDF (not overlay-only preview) via native Rust rasterization in the engine.
  • --deterministic-hash writes PDF SHA-256 by default; when --emit-image is set, it writes an artifact-set digest (fullbleed.artifact_digest.v1) computed from PDF SHA-256 plus ordered page-image SHA-256 values.

Reproducibility checks

Use --repro-record baseline.json to retain the input fingerprint and PDF digest from a reviewed render. Use --repro-check baseline.json on subsequent renders. Changed inputs or PDF bytes return a nonzero exit status with structured failure codes. The PDF and requested previews remain available for inspection.

Use 2.5.3 or newer for this gate: earlier versions could report a pass for an empty object or a record without hashes. Records must use fullbleed.repro_record.v1 and contain valid input_fingerprint_sha256 and output_pdf_sha256 values. Inspect the installed definition with fullbleed --schema repro-record.

Malformed records return REPRO_RECORD_INVALID. A recorded asset lock detects changes to its contents or presence with REPRO_LOCK_MISMATCH. To save a candidate record while checking, combine --repro-check baseline.json with --repro-record candidate.json; the paths must refer to different files. REPRO_RECORD_CONFLICT prevents a check from replacing its own baseline.

Keep the engine version, input data, options, metadata, and font/image bytes pinned. Use project-relative asset paths from a consistent working directory when sharing a baseline between machines. An input fingerprint may change even when the PDF looks the same. Inspect the PDF and every preview before intentionally recording a new baseline; CI should check the committed record, not refresh it. Matching bytes do not establish visual correctness, accessibility, or conformance.

PDF profiles

PDF profile targets include none, pdfa1a, pdfa1b, pdfa2a, pdfa2b, pdfa2u, pdfa3a, pdfa3b, pdfa3u, pdfa4, pdfa4e, pdfa4f, pdfx4, pdfua1, pdfua2, pdfvt1, wtpdf1r, wtpdf1a, and tagged. Aliases a, ua, vt, wt1r, wt1a, pdf/a, pdf/ua, and pdf/vt normalize to the canonical profile names in manifests and capability output. PDF/A and PDF/X/VT profiles require --output-intent-icc; PDF/A, PDF/X/VT, PDF/UA, and WTPDF text output requires embedded fonts and fails with an actionable font-asset hint. pdfa4, pdfa4e, pdfa4f, pdfua2, wtpdf1r, and wtpdf1a emit PDF 2.0 automatically.

Profile conformance gate:

pdfx4 and pdfvt1 force PDF 1.6 and require --document-title and an explicit --timestamp current, --timestamp YYYY-MM-DDTHH:MM:SSZ, or --timestamp-source SOURCE_DATE_EPOCH. --pdf-vt-job accepts a JSON description or path. See PDF/VT composition for grouping and DPM rules. render and verify parse the resulting print artifact and expose the internal writer contract result separately from independent conformance validation.

python tools/validate_pdf_profiles.py \
  --out output/conformance_validation \
  --download-verapdf \
  --install-pdf-oxide \
  --strict-external

The harness generates deterministic specimens for pdfa1a, pdfa1b, pdfa2a, pdfa2b, pdfa2u, pdfa3a, pdfa3b, pdfa3u, pdfa4, pdfa4e, pdfa4f, pdfua1, pdfua2, wtpdf1r, wtpdf1a, pdfx4, and pdfvt1; runs FullBleed inspect and JIT profile checks; replays each render for byte-for-byte SHA-256 determinism; runs veraPDF for PDF/A and PDF/UA; and runs pdf_oxide PDF/X-4 validation for pdfx4 and the PDF/X-4 base of pdfvt1. WTPDF profiles are validated with veraPDF wt1r/wt1a and checked for PDF Declaration evidence. PDF/A-4f is additionally checked for its associated EmbeddedFiles name tree. PDF/VT is additionally checked for PDF/VT identification, matching modification dates, and a parsed DPart graph: catalog DPartRoot, root DPartRootNode, NodeNameList [/Job /Record /Document], leaf DPart page range, and page /DPart references. The gate also renders a supplemental multipage PDF/VT specimen to prove the /Start and /End range. The inspect report exposes those PDF/VT graph checks as individual boolean fields as well as the aggregate pdfvt_dpart_graph_valid gate. A dedicated PDF/VT preflight tool is still required for third-party PDF/VT certification; wire one into the same gate with --pdfvt-cmd "tool --input {pdf}" --pdfvt-version-cmd "tool --version" --require-dedicated-pdfvt.

Default Fullbleed Python wheels are built with --features python,svg_raster. Use the same feature set for local source builds when testing --svg-raster-fallback.

verify

Same pipeline as render but tuned for validation/preflight usage. Can emit PDF optionally with --emit-pdf.

plan

Generates normalized compile manifest (fullbleed.compiler_input.v1) and warnings (for example remote refs without allow flag).

Use --emit-manifest <path> to persist manifest JSON.

Template composition planning:

  • with --templates + --template-binding, plan resolves template bindings and compose plan rows.
  • use --emit-compose-plan <path> to write fullbleed.compose_plan.v1.

run

Runs a Python entrypoint and renders with that returned engine:

fullbleed run report:engine --html input.html --css styles.css --out out.pdf

Entrypoint can be module:name or path/to/file.py:name.

finalize

Template composition command group:

  • fullbleed finalize stamp --template <template.pdf> --overlay <overlay.pdf> --out <final.pdf>
  • fullbleed finalize compose --templates <dir> --plan <plan.json> --overlay <overlay.pdf> --out <final.pdf>
  • Stamp placement controls: --dx <pt> --dy <pt> for explicit overlay translation when needed.

Current state:

  • stamp is implemented through the Rust core finalize path with strict checks and JSON result envelope
  • compose is implemented as a Rust-backed baseline with strict plan/catalog validation

inspect

Inspection command group:

  • fullbleed inspect pdf <path> [--json]
  • fullbleed inspect pdf-batch <path...> [--list paths.txt] [--json]
  • fullbleed inspect templates --templates <dir|json> [--json]

Use this to read canonical PDF metadata from the Rust inspector without rendering:

  • pdf_version
  • page_count
  • encrypted
  • file_size_bytes
  • composition compatibility (supported, issues)

Schema target:

  • fullbleed.inspect_pdf.v1
  • fullbleed.inspect_pdf_batch.v1
  • fullbleed.inspect_templates.v1

new

Template/project bootstrap command group:

  • Local templates:
    • fullbleed new local accessible <path>
    • fullbleed new local invoice <path>
    • fullbleed new local reference <path>
    • fullbleed new local statement <path>
    • Compatibility aliases are still supported:
      • fullbleed new accessible <path>
      • fullbleed new invoice <path>
      • fullbleed new reference <path>
      • fullbleed new statement <path>
  • Remote registry:
    • fullbleed new list [--registry <manifest-url>]
    • fullbleed new search <query> [--tag <tag>] [--registry <manifest-url>]
    • fullbleed new remote <template_id> [path] [--version latest|<x.y.z>] [--registry <manifest-url>]

Practical notes:

  • new local accessible seeds a verbose accessibility-first project that renders through fullbleed.accessibility.AccessibilityEngine and emits engine verifier, PMR, PDF/UA seed checks, and non-visual trace artifacts by default.
  • new local reference seeds the canonical static PDF reference scaffold, including component layers, local SVG/raster assets, page data, PDF/PNG previews, and validation reports.
  • Default registry URL can be overridden with --registry or FULLBLEED_TEMPLATE_REGISTRY.
  • new remote --dry-run resolves template/release metadata without downloading archives.
  • Remote install verifies archive SHA256 before extraction and blocks path traversal in zip contents.

init

fullbleed init <path> --json creates the standard project scaffold and reports artifacts plus structured next_actions. New projects include AGENTS.md so later coding-agent sessions retain the existing Fullbleed pipeline, inspect runtime capabilities before assuming support, render previews after layout changes, and validate before delivery.

Machine-mode schemas

--schema returns:

  • envelope schema: fullbleed.schema.v1
  • inferred target schema for the command/subcommand
  • schema definition when available

Examples:

fullbleed --schema render
fullbleed --schema assets list
fullbleed --schema inspect templates

Fail-on policy

Supported checks:

  • overflow
  • missing-glyphs
  • font-subst
  • budget

Budget limits:

  • --budget-max-pages
  • --budget-max-bytes
  • --budget-max-ms

Set --allow-fallbacks to permit fallback-related signals without failing.

Assets and cache commands

Use:

  • fullbleed assets install @bootstrap
  • fullbleed assets install inter
  • fullbleed assets lock
  • fullbleed cache dir
  • fullbleed cache prune --dry-run

Note:

  • @noto-sans remains available for broader glyph coverage, but it has a larger font payload and should be installed intentionally.

Project-aware installs default to ./vendor/; use --global for cache install behavior.

Compliance command

fullbleed compliance emits a policy report (fullbleed.compliance.v1) including:

  • licensing file checks
  • third-party notice checks
  • audit artifact staleness checks
  • MIT package-license metadata consistency

Use --strict for non-zero exit on flags.

Recommended CI usage

  1. Use --json-only outputs
  2. Enable --fail-on checks for your quality gates
  3. Emit deterministic and repro artifacts
  4. Parse command schema ids and output contracts in CI tooling