jsonx-cli 0.1.0
JSON query and transform CLI - simpler than jq
Requires Python: >=3.8
Keywords: automation, cli, jq, json, query, transform

# jsonx

JSON query and transform CLI — simpler than jq.

[![PyPI version](https://badge.fury.io/py/jsonx-cli.svg)](https://pypi.org/project/jsonx-cli/)

## Installation

```bash
pip install jsonx-cli
```

For JSON Schema validation:
```bash
pip install jsonx-cli[schema]
```

## Quick Start

```bash
# Get a nested value
jsonx get .users[0].name data.json

# From stdin
cat data.json | jsonx get .config.debug

# Set a value
jsonx set .config.debug true data.json

# List all keys
jsonx keys data.json

# Pretty print
jsonx format data.json
```

## Path Syntax

jsonx uses simple dot notation:

| Pattern | Meaning |
|---------|---------|
| `.key` | Object property |
| `.nested.key` | Nested property |
| `[0]` | Array index |
| `[-1]` | Last array item |
| `[*]` | All array items |
| `[0:3]` | Array slice |

Examples:
```bash
jsonx get .name data.json           # Get "name" property
jsonx get .users[0] data.json       # First user
jsonx get .users[-1] data.json      # Last user
jsonx get .users[*].email data.json # All user emails
jsonx get .items[0:5] data.json     # First 5 items
```

## Commands

### get - Extract values

```bash
jsonx get .path [file]          # Extract value at path
jsonx get .path file --raw      # Raw output (no quotes)
jsonx get .path file --json     # Force JSON output
```

### set - Modify values

```bash
jsonx set .path value [file]    # Set and output
jsonx set .path value file -i   # Modify in place
jsonx set .path value file -o out.json  # Write to file
```

Value is parsed as JSON:
```bash
jsonx set .debug true data.json           # boolean
jsonx set .count 42 data.json             # number
jsonx set .name '"Alice"' data.json       # string (note quotes)
jsonx set .tags '["a","b"]' data.json     # array
```

### del - Delete values

```bash
jsonx del .path [file]          # Delete and output
jsonx del .path file -i         # Delete in place
```

### keys - List keys

```bash
jsonx keys [file]               # Top-level keys
jsonx keys file -r              # All keys recursively
```

### flatten / unflatten - Structure transformation

```bash
# Flatten nested structure
jsonx flatten data.json
# {"users[0].name": "Alice", "config.debug": true}

# Unflatten back
echo '{"user.name": "Alice"}' | jsonx unflatten
# {"user": {"name": "Alice"}}
```

### merge - Combine files

```bash
jsonx merge base.json override.json     # Deep merge
jsonx merge a.json b.json --shallow     # Shallow merge
```

### diff - Compare files

```bash
jsonx diff old.json new.json
# + config.newKey: "value"      (green - added)
# - config.removed: true        (red - removed)  
# ~ config.changed: 1 → 2       (yellow - changed)
```

### format / minify - Pretty print

```bash
jsonx format data.json              # Pretty print
jsonx format data.json -i 4         # 4-space indent
jsonx minify data.json              # Compact
```

### validate - JSON Schema

```bash
jsonx validate data.json schema.json
# ✓ Valid
# or
# ✗ Invalid: 'email' is required
```

### type - Show value type

```bash
echo '[]' | jsonx type        # array
echo '{}' | jsonx type        # object
echo '42' | jsonx type        # integer
```

### count - Count items

```bash
jsonx count data.json                     # Top-level count
jsonx get .users data.json | jsonx count  # Count array items
```

### each - Iterate arrays

```bash
# Output each item as JSON
jsonx each data.json -p .users

# With template
jsonx each data.json -p .users -t '{.name}: {.email}'
```

## Piping

jsonx works great in pipelines:

```bash
# Extract, transform, merge
cat config.json | jsonx get .database | jsonx set .host '"prod.db"'

# Count users
jsonx get .users data.json | jsonx count

# Extract all emails
jsonx get .users[*].email data.json

# Filter and format
curl api/data | jsonx get .results | jsonx format
```

## For AI Agents

See [SKILL.md](SKILL.md) for agent-optimized documentation.

## Exit Codes

- `0` - Success
- `1` - Error (invalid JSON, path not found, etc.)

## License

MIT