JSON Schema Faker CLI

5.0.6 verified Thu Apr 23 auth: no javascript

json-schema-faker-cli provides a command-line interface (CLI) for the json-schema-faker library, enabling users to generate realistic mock data based on JSON schemas directly from the terminal without requiring programmatic JavaScript interaction. It is currently at version 5.0.6 and primarily serves as a utility for quick data generation. The tool allows specifying a JSON schema file, an optional output file, the number of items for array generation, and a separate options file (JS or JSON format) to customize the faker's behavior. While json-schema-faker itself is a library for programmatic use, this package differentiates itself by offering a shell-based workflow, making it ideal for scaffolding mock APIs, testing, or populating databases with dummy data through simple CLI commands. Its release cadence is generally tied to the underlying json-schema-faker library's evolution, offering a stable and straightforward interface.

Common errors

error command not found: generate-json ↓

cause The `json-schema-faker-cli` package has not been installed globally, or the `npm` global bin directory is not included in your system's PATH environment variable.

fix

Install the package globally using npm install -g json-schema-faker-cli or execute the command via npx for a temporary run: npx json-schema-faker-cli generate-json ...

error SyntaxError: Unexpected token '{' in JSON at position 1 (or similar JSON parsing error) ↓

cause The provided schema file (`schema.json`) or options file (`options.json`) contains malformed JSON, such as incorrect syntax, comments, or trailing commas, preventing it from being parsed correctly.

fix

Validate your schema.json and options.json files using a linter or online JSON validator. Ensure they strictly adhere to JSON syntax rules. If using a JS options file, confirm it's valid CommonJS.

error Error: Not a number: undefined (or similar type error related to array length argument) ↓

cause The array length parameter (the third argument) was provided with a non-numeric value, or it was incorrectly interpreted as `undefined` due to misplacement when skipping preceding optional parameters.

fix

Ensure the array length argument is a valid positive integer. If you are skipping previous arguments, make sure to use none placeholders correctly. For example, generate-json schema.json output.json 5 or generate-json schema.json none 5 options.js.

Warnings

breaking This CLI currently depends on a specific release candidate range of `json-schema-faker` (`^0.5.0-rc.21`). This means it may not be compatible with newer major versions of the underlying `json-schema-faker` library (e.g., `0.6.x` or `0.7.x`) which can introduce breaking changes to options, faker providers, or schema interpretation. Users should ensure their expectations align with the features and behaviors of the `0.5.x-rc` series. ↓

fix Check the `package.json` for the exact `json-schema-faker` version range it depends on. If you require features or fixes from a newer `json-schema-faker` release, consider using `json-schema-faker` programmatically in your own script or waiting for an update to `json-schema-faker-cli` that updates its dependency.

gotcha When skipping optional parameters to provide a later one (e.g., providing an options file but no output file), you must explicitly use `none` as a placeholder for each skipped parameter. Forgetting this will cause subsequent parameters to be misinterpreted by the CLI. ↓

fix If you want to skip the output file and array length but provide an options file, the correct syntax is `generate-json schema.json none none options.js`.

gotcha The options file can be either a plain JSON file or a CommonJS JavaScript file (`module.exports = { ... }`). If it's a JavaScript file, it must conform to CommonJS syntax, not ES Module (`export default { ... }`) syntax, as Node.js in the context of this CLI will load it as CommonJS. ↓

fix Ensure JavaScript options files use `module.exports = {...}`. For projects using ES Modules extensively, it's often simpler and more robust to use a `.json` options file for compatibility.

gotcha Outputting generated JSON to `stdout` (by omitting the output file path) is useful for piping to other commands, but can be problematic if the schema generates a very large JSON output, potentially flooding the terminal, causing performance issues, or making inspection difficult. ↓

fix For schemas generating large data or when generating multiple items, always specify an output file (`generate-json schema.json output.json`). Use `stdout` primarily for small, quick checks or when explicitly piping the output to another utility.

Install

npm install json-schema-faker-cli

yarn add json-schema-faker-cli

pnpm add json-schema-faker-cli

Imports

generate-json
wrong
```
import { generateJson } from 'json-schema-faker-cli'
```
correct
```
generate-json schema.json output.json
```
This package is a command-line interface tool and is not intended for programmatic import into JavaScript/TypeScript code. Its primary 'symbol' is the `generate-json` shell command, accessible after global installation or via `npx`.
Options file (JS)
wrong
```
export default { minLength: 20 };
```
correct
```
// options.js
module.exports = { minLength: 20 };
```
When providing a JavaScript options file to the CLI, it expects a CommonJS module (`module.exports`), not an ES Module (`export default`). The CLI performs the module loading internally.
Options file (JSON)
```
// options.json
{ "minLength": 20 }
```
A plain JSON file can also be used for options. Ensure it contains valid JSON syntax (no comments, no trailing commas) as the CLI will parse it directly.

Quickstart

Demonstrates global installation, basic single object generation, array generation, and usage with an external CommonJS options file, outputting to stdout or a file, then cleans up.

npm install -g json-schema-faker-cli

# Create a JSON schema file (e.g., schema.json)
cat > schema.json <<EOF
{
  "type": "object",
  "properties": {
    "id": { "type": "integer", "format": "uuid" },
    "name": { "type": "string", "faker": "name.findName" },
    "email": { "type": "string", "format": "email" },
    "createdAt": { "type": "string", "format": "date-time" }
  },
  "required": ["id", "name", "email"]
}
EOF

# Create an optional JavaScript options file (e.g., options.js)
cat > options.js <<EOF
module.exports = {
  minLength: 10,
  failOnInvalidFormat: false,
  random: () => 0.5 // Ensures consistent output for demo
};
EOF

echo "\n--- Generating a single object to stdout ---"
generate-json schema.json

echo "\n--- Generating a single object to 'output.json' ---"
generate-json schema.json output.json

echo "\n--- Generating an array of 3 objects to 'output-array.json' ---"
generate-json schema.json output-array.json 3

echo "\n--- Generating with custom options from 'options.js' to 'output-with-options.json' ---"
generate-json schema.json output-with-options.json none options.js

# Clean up generated files
rm schema.json output.json output-array.json output-with-options.json options.js