nip/docs/json-output.md

JSON Output Support

Overview

NIP provides comprehensive machine-readable output in multiple structured formats (JSON, YAML, KDL) for automation, tooling integration, and AI-friendly interfaces.

Output Formats

JSON Output

nip search firefox --json
nip list --json
nip show firefox --json

YAML Output

nip search firefox --yaml
nip list --yaml
nip show firefox --yaml

KDL Output

nip search firefox --kdl
nip list --kdl
nip show firefox --kdl

JSON Schema

Search Results

{
  "query": "firefox",
  "results": [
    {
      "name": "firefox",
      "version": "118.0",
      "description": "Mozilla Firefox web browser",
      "stream": "stable",
      "repository": "nexusos-stable",
      "install_status": "NotInstalled",
      "integrity_status": "Unknown",
      "size": 250000000,
      "install_date": null,
      "variants": [
        {
          "cid": "blake3-F21194C0A7BC",
          "cas_path": "/Programs/firefox/118.0-F21194C0A7BC/",
          "features": {},
          "build_flags": {},
          "toolchain": "gcc-13",
          "target": "x86_64-linux-gnu",
          "integrity_status": "Unknown"
        }
      ],
      "tags": ["browser", "gui"]
    }
  ],
  "total_found": 1,
  "cas_enabled": true,
  "variant_fingerprints": true
}

Package Information

{
  "name": "firefox",
  "version": "3.2.2",
  "description": "Interactive process viewer for Unix systems",
  "homepage": "https://htop.dev",
  "license": "GPL-2.0",
  "stream": "stable",
  "architecture": "x86_64",
  "installed": true,
  "install_date": "2025-08-05T10:30:00Z",
  "size": {
    "installed": 2048576,
    "download": 512000
  },
  "dependencies": [
    {
      "name": "libc",
      "version": ">=2.17",
      "type": "runtime"
    }
  ],
  "files": [
    "/System/Index/bin/htop"
  ],
  "build_hash": "blake3-abc123def456...",
  "acul_compliant": true
}

Integration Examples

Shell Scripting

# Get package count
PACKAGE_COUNT=$(nip list --json | jq '.total')

# Check if package is installed
IS_INSTALLED=$(nip show firefox --json | jq '.installed')

# Get CAS path
CAS_PATH=$(nip show firefox --json | jq -r '.variants[0].cas_path')

Python Integration

import subprocess
import json

def get_package_info(package_name):
    result = subprocess.run(['nip', 'show', package_name, '--json'],
                          capture_output=True, text=True)
    return json.loads(result.stdout)

package = get_package_info('firefox')
print(f"Package: {package['name']} v{package['version']}")
print(f"CAS Path: {package['variants'][0]['cas_path']}")

Use Cases

• CI/CD Integration: Automated package management in pipelines
• Infrastructure as Code: Declarative system configuration
• Monitoring: Package status and integrity monitoring
• AI Integration: Machine-readable package information
• Custom Tooling: Building package management tools
• Reporting: System inventory and compliance reporting