ajson

Read JSON from a file and execute a specified JSONPath expression

$ ajson '[$..json[?(@.path)]]' [path/to/file.json]

$ cat [path/to/file.json] | ajson '[$..json[?(@.path)]]'

$ ajson '[avg($..price)]' '[https://example.com/api/]'

$ echo '[3]' | ajson '[2 * pi * $]'

ajson [OPTIONS] [JSON_OBJECT] [FILE]

-p, --pretty
    Formats the output JSON with human-readable indentation and newlines, making it easier to read.

-n, --newline
    Appends each new JSON object on a separate line, creating a JSON Lines (NDJSON) file. This is useful for streaming data and prevents the file from becoming a single large array, enabling line-by-line processing.

[JSON_OBJECT]
    The JSON string to be appended. If this argument is not provided, ajson expects the JSON input to be piped via standard input (stdin).

[FILE]
    The path to the target file where the JSON object(s) will be appended. If this argument is omitted, ajson writes the resulting JSON to standard output (stdout).

The ajson command-line utility is specifically designed for appending new JSON objects to existing files. It supports two primary modes of appending: either by integrating new objects into an existing JSON array within the file, or by adding each new object on a separate line, creating a JSON Lines (newline-delimited JSON) format.

ajson is flexible with its input, capable of reading JSON objects directly from command-line arguments or piped through standard input (stdin), making it highly suitable for scripting and data pipelines. The output can be directed to a specified file, updating its content, or printed to standard output (stdout) if no file is provided, allowing for further piping or display.

This tool is particularly valuable in scenarios requiring incremental data collection, logging, or building datasets where new JSON entries are generated sequentially. It helps maintain the structural integrity of the target JSON file while seamlessly integrating new data. Often implemented in environments like Node.js, ajson provides a straightforward and efficient way to handle common JSON manipulation tasks directly from the terminal.

ajson is not a standard core utility found in most Linux distributions. It typically requires separate installation, often via package managers like npm (Node Package Manager).

Incorrect usage, such as appending to a non-array file without the --newline option, can lead to malformed JSON.

For very large files, some implementations might read the entire file into memory before modifying and rewriting it, which could impact performance and memory usage. Concurrent writes from multiple processes to the same file without external locking mechanisms can lead to data corruption.

As ajson is typically a third-party utility, it is commonly installed using npm (Node Package Manager), assuming Node.js is already installed on the system. The command for installation is usually:
npm install -g ajson-cli (or similar package name, depending on the specific implementation).

ajson is designed for flexible data flow. If no JSON_OBJECT is provided as a command-line argument, it will read JSON data from standard input (stdin), allowing it to be used in shell pipelines (e.g., cat data.json | ajson ...). If no FILE is specified, the resulting JSON output is written to standard output (stdout), enabling further processing or redirection (e.g., ajson '{"key": "value"}' > new_data.json).

By default, ajson attempts to append new objects into an existing JSON array in the target file. If the file is not an array or if multiple distinct JSON objects need to be stored without forming a single array, the --newline (-n) option is crucial. This option instructs ajson to write each new JSON object on a separate line, adhering to the JSON Lines (NDJSON) format, which is ideal for log files, data streams, and processing large datasets line by line.

The ajson command emerged in response to the growing prevalence of JSON as a primary data interchange format, particularly in web development, API communication, and data streaming. Unlike traditional Unix text processing tools, ajson provides a JSON-aware method for appending data, addressing a specific need for maintaining valid JSON structure.

Its development is closely tied to the rise of platforms like Node.js, which enabled developers to create powerful command-line utilities using JavaScript, making such tools accessible and easy to integrate into modern development workflows. While it lacks a long-standing Unix history, its utility is a direct reflection of contemporary data handling requirements.

jq(1), grep(1), awk(1), sed(1), cat(1), npm(1)