Metadata-Version: 2.4
Name: jqstash
Version: 0.1.1
Summary: Terminal UI for jq filter management
License-Expression: MIT
Project-URL: Homepage, https://github.com/erkanguzeler/jqstash
Requires-Python: >=3.12
Description-Content-Type: text/markdown
Requires-Dist: textual[syntax]>=8.2
Requires-Dist: pyperclip>=1.9

# JqStash

A terminal UI for exploring JSON and managing your `jq` filters — paste JSON, tweak a filter, see the result live, save the ones you'll want again.

No database, no server. Everything is a local JSON file (`~/.jq_queries.json`).

## Features

- **Live filter editing** — type a `jq` filter and see results update as you type (debounced, no lag)
- **Saved queries** — name, describe, and tag your favorite filters; browse and preview them with `↑`/`↓`
- **Syntax highlighting** — JSON input and results are colorized (Monokai theme, via `textual[syntax]`)
- **One-key formatting** — `Ctrl+F` pretty-prints the pasted JSON
- **Search** — filter your saved query list by name, filter text, description, or tag
- **Clipboard in/out** — paste JSON with `Ctrl+V`, copy results with `Ctrl+C`
- **Load from file** — `Ctrl+O` to pull JSON straight from disk
- **Usage tracking** — each saved query records how often and when it was last run

## Screenshot

_TODO: add a screenshot or asciinema recording here._

## Requirements

- Python 3.12+
- [`jq`](https://jqlang.github.io/jq/) on your `PATH`

## Install

**From PyPI (recommended):**

```bash
pip install jqstash
jqstash
```

**From source:**

```bash
git clone https://github.com/coderkan/jqstash.git
cd jqstash
python3 -m venv venv
./venv/bin/pip install -r requirements.txt
./venv/bin/python main.py
```

## Keyboard shortcuts

| Key       | Action                              |
|-----------|--------------------------------------|
| `Ctrl+V`  | Paste JSON into the input pane      |
| `Ctrl+O`  | Load JSON from a file               |
| `Ctrl+F`  | Format / pretty-print the JSON input |
| `Tab`     | Move focus between panes            |
| `↑` / `↓` | Browse saved queries (live preview) |
| `Enter`   | Run the highlighted saved query     |
| `/`       | Search saved queries                |
| `N`       | Save the current filter as a new query |
| `D`       | Delete the highlighted query        |
| `Ctrl+C`  | Copy the results pane to clipboard  |
| `Esc`     | Clear input, or close search/quit   |
| `Q`       | Quit                                |

## How it works

- JSON goes in the left pane, your `jq` filter goes in the FILTER box — both are live-wired, so editing either one re-runs the query immediately.
- Selecting a saved query from the list loads its filter into the FILTER box so you can tweak it without touching the original — hit `N` to save your tweaked version separately.
- `jq` itself runs as a subprocess, so you get full compatibility with whatever `jq` version is on your machine.

## Query storage format

Saved queries live in `~/.jq_queries.json`:

```json
{
  "version": "1.0",
  "queries": [
    {
      "id": "q_001",
      "name": "Active Crew IDs",
      "filter": ".crew[] | select(.active==true) | .id",
      "description": "Get all active crew member IDs",
      "tags": ["crew"],
      "created_at": "2026-08-03T10:15:00+00:00",
      "last_used": "2026-08-03T12:30:00+00:00",
      "usage_count": 5
    }
  ]
}
```

It's plain JSON, so it's easy to back up, sync, or edit by hand.

## Tech stack

| Component | Choice | Why |
|-----------|--------|-----|
| TUI | [`textual`](https://textual.textualize.io/) | Rich widgets, fast, cross-platform |
| Filtering | `jq` subprocess | No reimplementation, full compatibility |
| Storage | JSON file | No DB, portable, git-friendly |
| Clipboard | `pyperclip` | Cross-platform copy/paste |

## License

TODO — pick a license (MIT is a common default) and add a `LICENSE` file.
