{"id":14415,"library":"ajv-cmd","title":"AJV Command Line Interface","description":"ajv-cmd provides a robust command-line interface (CLI) for performing essential operations on JSON Schema files, leveraging the powerful AJV (Another JSON Schema Validator) library. It enables users to dereference, validate, transpile, and test JSON Schema definitions directly from the terminal, streamlining schema management and integration into build processes. The current stable version is 0.12.0. While no explicit release cadence is stated, its `0.x.x` versioning coupled with recent GitHub activity suggests active development and potentially rapid iterations. A key differentiator is its modern approach, requiring Node.js 24+, and its commitment to supply chain security standards like SLSA 3 and OpenSSF Scorecard, building upon the foundation of `ajv-cli` with a focus on contemporary JavaScript environments and best practices. It's primarily designed for developers who need to automate schema validation and compilation within CI/CD pipelines or local development workflows, providing a convenient wrapper around AJV's extensive capabilities.","status":"active","version":"0.12.0","language":"javascript","source_language":"en","source_url":"https://github.com/willfarrell/ajv-cmd","tags":["javascript","json","schema","json-schema","ajv","compiler","transpiler"],"install":[{"cmd":"npm install ajv-cmd","lang":"bash","label":"npm"},{"cmd":"yarn add ajv-cmd","lang":"bash","label":"yarn"},{"cmd":"pnpm add ajv-cmd","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core JSON Schema validation and compilation engine.","package":"ajv","optional":false},{"reason":"Used for parsing command-line arguments and structuring the CLI.","package":"commander","optional":false}],"imports":[{"note":"ajv-cmd is primarily a CLI tool. While the core command logic is exported from internal paths, these are not considered a stable public API and are subject to change between minor versions. Prefer CLI usage (`ajv validate ...`).","symbol":"validate","correct":"import { validate } from 'ajv-cmd/src/commands/validate.js'"},{"note":"Similar to `validate`, the `transpile` function is exported from an internal path. This package's primary interface is its command-line utility. Direct programmatic use via these internal paths is discouraged for stability reasons.","symbol":"transpile","correct":"import { transpile } from 'ajv-cmd/src/commands/transpile.js'"},{"note":"The `test` function, like other command logic, is exported from an internal module path. Relying on these internal paths for programmatic use is not recommended due to potential breaking changes in non-major versions. Use the `ajv test` CLI command instead.","symbol":"test","correct":"import { test } from 'ajv-cmd/src/commands/test.js'"}],"quickstart":{"code":"#!/usr/bin/env bash\n\n# Install ajv-cmd as a development dependency\nnpm install -D ajv-cmd\n\n# Define a function to validate and transpile a schema\nfunction bundle_schema {\n  # Validate the schema with strict mode, type coercion, all errors, and default values\n  ajv validate \"${1}\" --valid \\\n    --strict true --coerce-types array --all-errors true --use-defaults empty\n\n  # Transpile the schema to a JavaScript file\n  ajv transpile \"${1}\" \\\n    --strict true --coerce-types array --all-errors true --use-defaults empty \\\n    -o \"${1%.json}.js\"\n}\n\n# Create a dummy schema file for demonstration\nmkdir -p handlers/user\necho '{\n  \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n  \"type\": \"object\",\n  \"properties\": {\n    \"name\": { \"type\": \"string\" },\n    \"age\": { \"type\": \"integer\", \"minimum\": 0, \"default\": 18 }\n  },\n  \"required\": [\"name\"]\n}' > handlers/user/schema.create.json\n\n# Loop through all schema files in handlers/ and process them\nfor file in handlers/*/schema.*.json; do\n  echo \"Processing: $file\"\n  if ! bundle_schema \"$file\"; then\n    echo \"$file failed processing.\" >&2\n    exit 1\n  fi\n  echo \"Successfully processed $file\"\ndone\n\necho \"\\nCheck the 'handlers/' directory for generated JS files.\"\n\n# Clean up dummy schema file\n# rm -rf handlers/","lang":"bash","description":"This quickstart demonstrates how to install `ajv-cmd` and use its `validate` and `transpile` commands within a bash script to process multiple JSON Schema files. It shows common `ajv` options for strict validation and transpilation."},"warnings":[{"fix":"Upgrade your Node.js environment to version 24 or newer. Consider using a Node Version Manager (NVM) to manage multiple Node.js installations.","message":"ajv-cmd requires Node.js version >=24. Running it with older Node.js versions will result in an error.","severity":"breaking","affected_versions":">=0.1.0"},{"fix":"Pin your `ajv-cmd` dependency to a specific minor version (e.g., `\"ajv-cmd\": \"~0.12.0\"`) or explicitly test upgrades across minor versions.","message":"The package is in `0.x.x` versioning, indicating that its API and CLI options may undergo breaking changes in minor releases. Always review release notes when upgrading.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Prefer using `ajv-cmd` strictly as a command-line interface tool, as it is primarily designed for this purpose. If programmatic access is essential, consider using the underlying `ajv` library directly.","message":"When using `ajv-cmd` programmatically via internal paths (e.g., `ajv-cmd/src/commands/validate.js`), these paths are implementation details and not part of the public API. They are highly susceptible to change without notice, leading to import errors.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Thoroughly test your schemas and data with these options. Refer to the official AJV documentation for a complete understanding of strict mode and type coercion behavior. Start with less strict options and gradually enable them as needed.","message":"Using strict validation modes (e.g., `--strict true`) and type coercion (`--coerce-types`) can lead to unexpected validation failures or data transformations if not fully understood, especially with complex schemas.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"When installed locally, use `npx ajv ...` or add `./node_modules/.bin` to your system's PATH. If installed globally (`npm install -g ajv-cmd`), ensure your global `npm` bin directory is in your PATH.","cause":"The `ajv-cmd` package's executable (`ajv`) is not in your system's PATH. This usually happens when installed locally without using `npx` or without adding `node_modules/.bin` to PATH.","error":"ajv: command not found"},{"fix":"Update your Node.js environment to version 24 or higher. Use a Node Version Manager (e.g., `nvm install 24`, `nvm use 24`) to easily switch versions.","cause":"You are running `ajv-cmd` with an incompatible Node.js version.","error":"Error: This package requires Node.js version >=24."},{"fix":"Carefully review your JSON Schema for syntax errors, incorrect keywords, or violations of the JSON Schema specification. Use a schema linter or online validator to pinpoint issues.","cause":"Your JSON Schema contains an error preventing successful validation or compilation by AJV.","error":"Schema failed validation: keyword 'type' expected string, got object at #/properties/name"},{"fix":"Avoid importing directly from `ajv-cmd/src/...` paths. This package is designed for command-line use. If programmatic validation or transpilation is required, use the core `ajv` library directly or rely on `ajv-cmd` via `child_process` (e.g., `execa`).","cause":"You are attempting to import an internal module path of `ajv-cmd` that either does not exist, has changed, or is not intended for public consumption.","error":"Error: Cannot find module 'ajv-cmd/src/commands/validate.js'"}],"ecosystem":"npm"}