nexart.iodocs

    NexArt CLI

    Command-line surface over the AI Execution SDK. Seal locally, certify optionally, verify anywhere.

    CLI commands map directly to this flow.

    NexArt Integration (Canonical Flow)

    Flow:

    1. Capture execution input
    2. Seal locally (offline)
    3. Verify locally
    4. (Optional) Certify via node
    5. Verify again

    Verification outcomes:

    • Sealed → Integrity: PASS, Receipt: SKIPPED, Envelope: SKIPPED
    • Certified → Integrity: PASS, Receipt: PASS, Envelope: PASS

    Rules:

    • Sealing does NOT require a node
    • Certification is OPTIONAL
    • Verification does NOT require trust
    • SKIPPED is expected for local artifacts and is NOT a failure

    Do NOT:

    • call the node before sealing
    • recompute hashes manually
    • modify bundles after sealing
    • treat SKIPPED as failure

    Technical truth

    What a CER is
    A Certified Execution Record (CER) is a canonical, tamper-evident bundle representing one execution. It has bundleType: "cer.ai.execution.v1", a version, a createdAt ISO-8601 timestamp, a snapshot (model, inputHash, outputHash, metadata), and an optional context / contextSummary. The CER is identified by its certificateHash (SHA-256). Inputs and outputs are stored as hashes; raw payloads are not part of the bundle.
    Fields covered by certificateHash (whitelist)
    The hash is SHA-256 over a strict whitelist projection, canonicalized per the profile selected by protocolVersion (1.2.0 → nexart-v1, default; 1.3.0 → jcs-v1, RFC 8785, opt-in). Whitelist:bundleType, version, createdAt, snapshot, and (only when present) context, contextSummary, policyEvaluation. Any modification to a covered field changes the hash. Canonicalization is protocol-bound: verifiers MUST use the profile corresponding to the bundle's protocolVersion.
    Fields excluded from hashing
    The following are explicitly excluded from the hash payload and may be added, updated, or removed without invalidating the certificateHash: certificateHash itself, meta (including meta.attestation and the receipt), declaration, verificationEnvelope, verificationEnvelopeSignature, receipt, and any unknown fields not in the whitelist. Verifiers MUST apply the whitelist projection to the bundle as received; no reconstruction beyond the canonicalization profile bound to the bundle's protocolVersion.
    The three verification layers
    • certificateHash (integrity) — recompute SHA-256 over the JCS-canonicalized whitelist projection and compare with the bundle's certificateHash.
    • receipt signature (node attestation) — validate the Ed25519 receipt at meta.attestation using the node key matched by kid, and confirm it references the bundle's certificateHash.
    • verification envelope (full bundle signature, v0.16.1) — validate meta.verificationEnvelopeSignature against meta.verificationEnvelope. When absent, this layer returns SKIPPED.

    Each layer reports independently as PASS, FAIL, or SKIPPED. Verification statuses: VERIFIED, FAILED, NOT_FOUND.

    Independence model: local sealing, optional node certification, independent verification

    Local sealing — produced by the SDK (@nexart/ai-execution@1.0.0 via sealCer()) or the CLI (@nexart/cli@1.0.0 via nexart ai seal). Builds a canonical CER bundle and computes the certificateHash fully offline. No API key, no network call, no receipt, no verification envelope. The result is a sealed bundle: integrity only.

    Optional node certification — performed by the attestation node (POST /v1/cer/ai/certify / nexart ai certify). The node validates the bundle and issues an Ed25519-signed receipt (identified by kid) referencing the bundle's certificateHash, plus a verification envelope. Receipt and signatures are stored at bundle.meta.attestation and meta.verificationEnvelope. Certification adds attestation layers; it does not change the certificateHash. The result is a certified bundle.

    Independent verification — performed by anyone, with no trust in NexArt infrastructure required. Available via verify.nexart.io, the SDK, or the CLI. The bundle plus the node's published public keys are sufficient. For sealed bundles, only Layer 1 (integrity) is applicable; Layers 2 and 3 return SKIPPED. For certified bundles, all three layers return PASS.

    Best For

    • Local development and testing
    • Offline sealing of CER bundles (no network, no API key)
    • Offline verification of CER bundles and CER packages
    • CI pipelines and automation scripts

    Architecture: CLI is a delegation layer

    As of @nexart/cli@1.0.0, the CLI contains zero CER cryptographic logic. Every operation is delegated to @nexart/ai-execution@1.0.0:

    • SDK owns: snapshot creation, protocol-bound canonicalization (nexart-v1 / jcs-v1), hashing, sealing, verification logic.
    • CLI owns: command surface, file I/O, argument parsing, output formatting.
    • Node owns: attestation, Ed25519 receipt signing, verification envelope signature.

    The CLI does not recompute hashes, does not canonicalize JSON, and does not validate signatures. It routes input to the SDK and prints what the SDK returns.

    Canonical workflow

    The recommended order for any new integration:

    seal -> verify -> (optional) certify -> verify
    # 1. Seal locally (offline, no API key)
npx @nexart/cli@1.0.0 ai seal execution.json --out cer.json

# 2. Verify the sealed bundle
npx @nexart/cli@1.0.0 ai verify cer.json
# integrity: PASS, receipt: SKIPPED, envelope: SKIPPED

# 3. (Optional) Certify via the attestation node
export NEXART_NODE_ENDPOINT="https://node.nexart.io"
export NEXART_API_KEY="<your-api-key>"
npx @nexart/cli@1.0.0 ai certify execution.json --out cer.certified.json

# 4. Verify again (now attested)
npx @nexart/cli@1.0.0 ai verify cer.certified.json
# integrity: PASS, receipt: PASS, envelope: PASS

    Sealed vs Certified

    PropertySealed (local)Certified (node)
    OriginSDK / CLI, fully offlineAttestation node (POST /v1/cer/ai/certify)
    API key requirednoyes (NEXART_API_KEY)
    certificateHashpresentpresent (identical input → identical hash)
    meta.attestation (receipt)absentpresent, Ed25519-signed
    meta.verificationEnvelopeabsentpresent (v0.16.1)
    Layer 1 — IntegrityPASSPASS
    Layer 2 — ReceiptSKIPPEDPASS
    Layer 3 — EnvelopeSKIPPEDPASS
    Third-party verifiableintegrity onlyyes (attested)

    SKIPPED is not a failure. A sealed bundle is a valid CER; it simply has not been attested by a node. Certification adds Layers 2 and 3 without changing thecertificateHash.

    Installation

    Install / Help
    npx @nexart/cli@1.0.0 --help

    Environment Variables

    • NEXART_API_KEY: required for ai certify. Not required for ai seal or ai verify.
    • NEXART_NODE_ENDPOINT: attestation node URL. Required for ai certify.
    • NEXART_RENDERER_ENDPOINT: URL of the canonical renderer service (for deterministic rendering workflows).

    nexart ai seal (v0.8.1+)

    Seal an execution into a CER bundle fully offline. No node call, no API key, no network access. Delegates to the SDK functions createSnapshot() and sealCer().

    Input contract

    The input file MUST be a JSON object matching CreateSnapshotParams exactly, as defined by @nexart/ai-execution@1.0.0:

    execution.json (CreateSnapshotParams)
    {
  "executionId": "demo-001",
  "provider": "openai",
  "model": "gpt-4o-mini",
  "input": {
    "messages": [
      { "role": "user", "content": "Should this report be approved?" }
    ]
  },
  "output": {
    "decision": "approve",
    "reason": "policy_passed"
  }
}

    Command

    Seal a CER
    npx @nexart/cli@1.0.0 ai seal execution.json --out cer.json

    Output

    The command writes a CER bundle with:

    • bundleType: "cer.ai.execution.v1"
    • version: "0.1"
    • computed certificateHash (SHA-256 over JCS-canonicalized whitelist projection)
    • no meta.attestation
    • no receipt
    • no verification envelope

    Verification result for a sealed bundle

    ai verify (sealed bundle)
    {
  "status": "VERIFIED",
  "integrity": "PASS",
  "receipt":   "SKIPPED",
  "envelope":  "SKIPPED",
  "cli": {
    "inputType": "bundle",
    "cliVersion": "0.8.1"
  }
}

    SKIPPED is not a failure. It means the layer does not apply to a sealed (non-attested) bundle. The bundle is a fully valid CER; it has just not been certified by a node.

    nexart ai certify

    Send an execution to the NexArt attestation node for certification. The node returns a signed Ed25519 receipt and a verification envelope. Requires NEXART_API_KEY and NEXART_NODE_ENDPOINT.

    Certify
    npx @nexart/cli@1.0.0 ai certify execution.json --out cer.certified.json
    Certify Result
    CER certified
certificateHash: sha256:...
verificationUrl: https://verify.nexart.io/c/sha256:...

    The certified bundle has identical certificateHash to a sealed bundle created from the same input. Certification adds meta.attestation and meta.verificationEnvelope without modifying any hashed field.

    nexart ai verify

    As of v0.8.1, nexart ai verify is a pure delegation to verifyAiCerBundleDetailed() in @nexart/ai-execution@1.0.0. The CLI:

    • does not recompute the certificateHash
    • does not canonicalize JSON
    • does not validate signatures
    • only routes the input file to the SDK and formats the SDK's result

    The command accepts both raw CER bundles and CER packages.

    Verify a sealed (local) CER bundle

    Verify Sealed Bundle
    npx @nexart/cli@1.0.0 ai verify cer.json
    Sealed bundle result
    {
  "status": "VERIFIED",
  "integrity": "PASS",
  "receipt":   "SKIPPED",
  "envelope":  "SKIPPED",
  "cli": {
    "inputType": "bundle",
    "cliVersion": "0.8.1"
  }
}

    Verify a certified CER bundle

    Verify Certified Bundle
    npx @nexart/cli@1.0.0 ai verify cer.certified.json
    Certified bundle result
    {
  "status": "VERIFIED",
  "integrity": "PASS",
  "receipt":   "PASS",
  "envelope":  "PASS",
  "cli": {
    "inputType": "bundle",
    "cliVersion": "0.8.1"
  }
}

    Verify a CER package

    When the input is a CER package, the CLI extracts and verifies the inner CER bundle through the SDK. Package-level trust layers (e.g. verification envelope at the package wrapper) are not fully verified by this command.

    Verify CER Package
    npx @nexart/cli@1.0.0 ai verify package.json
    Package result
    {
  "status": "VERIFIED",
  "integrity": "PASS",
  "receipt":   "PASS",
  "envelope":  "PASS",
  "cli": {
    "inputType": "package",
    "verifiedInnerCer": true,
    "packageTrustLayersVerified": false,
    "cliVersion": "0.8.1"
  }
}

    Output schema: top-level fields (status, integrity, receipt, envelope) come directly from the SDK. cli.* fields are additive CLI metadata and do not participate in verification semantics.

    Use in Automation or CI

    CI Example
    # Seal locally during build (offline, no secrets)
npx @nexart/cli@1.0.0 ai seal execution.json --out cer.json
npx @nexart/cli@1.0.0 ai verify cer.json

# Certify on release (requires API key)
npx @nexart/cli@1.0.0 ai certify execution.json --out cer.certified.json
npx @nexart/cli@1.0.0 ai verify cer.certified.json

    Context Signals

    Attach structured metadata to a CER using a signals file. Signals are included in the certificateHash.

    With Signals
    npx @nexart/cli@1.0.0 ai seal    execution.json --signals-file signals.json
npx @nexart/cli@1.0.0 ai certify execution.json --signals-file signals.json

    See Context Signals for the full specification.

    Deterministic Rendering

    The CLI also supports deterministic rendering workflows for canvas-based executions:

    Run a Render
    npx @nexart/cli@1.0.0 run ./examples/sketch.js \
  --seed 12345 \
  --vars "50,50,50,0,0,0,0,0,0,0" \
  --include-code \
  --out out.png
    Verify a Snapshot
    npx @nexart/cli@1.0.0 verify out.snapshot.json

    Versions

    • CLI: @nexart/cli@1.0.0
    • SDK: @nexart/ai-execution@1.0.0
    • Bundle version: "0.1"
    • Protocol version (default): 1.2.0 (nexart-v1)
    • Protocol version (opt-in): 1.3.0 (jcs-v1, RFC 8785) via --protocol-version 1.3.0

    Next Steps