Node.js Wrapper (npm)¶

Install CapiscIO CLI via npm

The capiscio npm package provides an npm-installable wrapper for the CapiscIO CLI.

Installation¶

Global Installation (Recommended)¶

npm install -g capiscio

Local Installation¶

npm install capiscio

With local installation, run via npx:

npx capiscio validate agent-card.json

How It Works¶

When you run npm install capiscio:

Detects your OS (Linux, macOS, Windows) and architecture (x64, ARM64)
Downloads the correct capiscio-core binary via postinstall script
Creates a capiscio command that proxies to the binary

Usage¶

After installation, use capiscio directly from your terminal:

# Validate an agent card
capiscio validate agent-card.json

# Validate with JSON output
capiscio validate agent-card.json --json

# Test live endpoint
capiscio validate https://agent.example.com --test-live

# Strict validation mode
capiscio validate agent-card.json --strict

All CLI flags are identical to the core binary. See CLI Reference for the complete command reference.

Package Scripts Integration¶

Add validation to your package.json:

{
  "scripts": {
    "validate": "capiscio validate agent-card.json",
    "validate:strict": "capiscio validate agent-card.json --strict",
    "validate:json": "capiscio validate agent-card.json --json"
  },
  "devDependencies": {
    "capiscio": "^0.3.0"
  }
}

Then run:

npm run validate

CI/CD Usage¶

GitHub Actions¶

- name: Setup Node.js
  uses: actions/setup-node@v4
  with:
    node-version: '20'

- name: Install CapiscIO
  run: npm install -g capiscio

- name: Validate Agent
  run: capiscio validate agent-card.json --strict

GitLab CI¶

validate:
  image: node:20
  script:
    - npm install -g capiscio
    - capiscio validate agent-card.json --strict

Programmatic Usage¶

CLI Wrapper Only

The npm package is a CLI wrapper only. It does not expose a TypeScript/JavaScript API for programmatic validation.

For programmatic validation in Node.js, spawn the CLI as a child process:

import { execSync } from 'child_process';

function validateAgentCard(path: string): ValidationResult {
  const result = execSync(`npx capiscio validate ${path} --json`, {
    encoding: 'utf-8',
  });
  return JSON.parse(result);
}

// Usage
const result = validateAgentCard('./agent-card.json');
console.log('Compliance:', result.scoringResult.complianceScore);

For a full TypeScript SDK, see the Python SDK or consider contributing a Node.js SDK.

Troubleshooting¶

Binary Download Fails¶

If the postinstall script fails:

# Remove and reinstall
npm uninstall capiscio
npm install capiscio

Permission Errors (Global Install)¶

If you get EACCES errors:

# Option 1: Use npx instead
npx capiscio validate agent-card.json

# Option 2: Fix npm permissions
# See: https://docs.npmjs.com/resolving-eacces-permissions-errors

Platform Not Supported¶

The wrapper supports: - Linux: x64, ARM64 - macOS: x64 (Intel), ARM64 (Apple Silicon) - Windows: x64