NexArt CLI — Command Line Reference

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.3.0, the CLI contains zero CER cryptographic logic. Every operation is delegated to @nexart/ai-execution@1.4.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:

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

# 2. Verify the sealed bundle
npx @nexart/cli@1.3.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.3.0 ai certify execution.json --out cer.certified.json

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

Installation

npx @nexart/cli@1.3.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

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

--protocol-version accepts 1.2.0, 1.3.0, or 1.3.1. Producing a V2 record (cer.ai.execution.v2) always uses protocolVersion 1.3.1 (jcs-v1); an unsupported value fails closed with SCHEMA_ERROR / SCHEMA_VERSION_UNSUPPORTED, exit code 1.

Input contract

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

{
  "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

npx @nexart/cli@1.3.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 the canonicalized whitelist projection, profile bound to snapshot.protocolVersion)
• no meta.attestation
• no receipt
• no verification envelope

Verification result for a sealed bundle

{
  "status": "VERIFIED",
  "integrity": "PASS",
  "receipt":   "SKIPPED",
  "envelope":  "SKIPPED",
  "cli": {
    "inputType": "bundle",
    "cliVersion": "1.3.0"
  }
}

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.

npx @nexart/cli@1.3.0 ai certify execution.json --out cer.certified.json

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

nexart ai verify is a pure delegation to the SDK's verification functions in @nexart/ai-execution@1.4.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

Dual-schema verification (v1 and v2)

As of CLI 1.3.0, ai verify handles both cer.ai.execution.v1 and cer.ai.execution.v2 bundles, dispatching to the matching SDK verifier by bundleType. Confidential V2 records can be verified offline, without openings: base V2 verification (verifyCerV2) checks integrity and the protected-set commitment without needing the producer's disclosed commitment openings.

An unsupported protocolVersion fails closed: the CLI reports SCHEMA_ERROR or SCHEMA_VERSION_UNSUPPORTED and exits with code 1. It never guesses a schema or silently downgrades verification strictness.

AIEF projection (--aief)

nexart ai verify --aief runs the AIEF v0.2.5 Section 9 projection (verifyAief) against a V1 or V2 bundle and prints the PASS / FAIL result plus the underlying checks (schemaSupported, integrityValid, protectedSetValid, chainValid). Exit code 0 means PASS; exit code 1 means FAIL.

npx @nexart/cli@1.3.0 ai verify cer-v2.json --aief

V2 output: requested model vs producer-transcribed evidence

For a V2 bundle, human-readable output shows the requested/producer-declared model alongside modelEvidence.responseDeclaredModel when present, labelled explicitly as producer-transcribed. The CLI never overwrites model with the response value; both are shown as distinct fields because modelEvidence is producer-transcribed, never provider-signed proof.

{
  "status": "VERIFIED",
  "verdict": "VERIFIED",
  "model": "gpt-4o",
  "modelEvidence": {
    "responseDeclaredModel": "gpt-4o-2024-08-06 (producer-transcribed)"
  }
}

The command accepts both raw CER bundles and CER packages.

Verify a sealed (local) CER bundle

npx @nexart/cli@1.3.0 ai verify cer.json

{
  "status": "VERIFIED",
  "integrity": "PASS",
  "receipt":   "SKIPPED",
  "envelope":  "SKIPPED",
  "cli": {
    "inputType": "bundle",
    "cliVersion": "1.3.0"
  }
}

Verify a certified CER bundle

npx @nexart/cli@1.3.0 ai verify cer.certified.json

{
  "status": "VERIFIED",
  "integrity": "PASS",
  "receipt":   "PASS",
  "envelope":  "PASS",
  "cli": {
    "inputType": "bundle",
    "cliVersion": "1.3.0"
  }
}

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.

npx @nexart/cli@1.3.0 ai verify package.json

{
  "status": "VERIFIED",
  "integrity": "PASS",
  "receipt":   "PASS",
  "envelope":  "PASS",
  "cli": {
    "inputType": "package",
    "verifiedInnerCer": true,
    "packageTrustLayersVerified": false,
    "cliVersion": "1.3.0"
  }
}

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

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

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

Context Signals

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

npx @nexart/cli@1.3.0 ai seal    execution.json --signals-file signals.json
npx @nexart/cli@1.3.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:

npx @nexart/cli@1.3.0 run ./examples/sketch.js \
  --seed 12345 \
  --vars "50,50,50,0,0,0,0,0,0,0" \
  --include-code \
  --out out.png

npx @nexart/cli@1.3.0 verify out.snapshot.json

Versions

• CLI: @nexart/cli@1.3.0
• SDK: @nexart/ai-execution@1.4.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

• Quickstart: seal then verify in three steps
• Architecture: SDK / CLI / Node ownership boundaries
• Verification: layer-by-layer semantics
• AI Execution SDK: programmatic seal and certify
• LangChain / n8n: framework integrations