# Nclq

> Query, filter, inspect, and extract data from Nickel (.ncl) files using nclq. Use when the user asks to look at, count, filter, search, or analyze data inside .ncl files, or when you encounter a .ncl file and need to understand its contents.

- **Type:** Skill
- **Install:** `agentstack add skill-louloulibs-claude-skills-nclq`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [LouLouLibs](https://agentstack.voostack.com/s/louloulibs)
- **Installs:** 0
- **Category:** [Search](https://agentstack.voostack.com/c/search)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [LouLouLibs](https://github.com/LouLouLibs)
- **Source:** https://github.com/LouLouLibs/claude-skills/tree/main/skills/nclq

## Install

```sh
agentstack add skill-louloulibs-claude-skills-nclq
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# nclq — Nickel Query Tool

Query nickel files using nickel expressions. Top-level fields are automatically in scope — no import boilerplate needed.

## Quick Reference

```bash
# View a file (auto-detect: no expression needed)
nclq data.ncl
nclq data.ncl --compact

# Single file — fields in scope
nclq '' file.ncl

# Multi-file — named bindings
nclq '' -f name1=file1.ncl -f name2=file2.ncl

# Stdin
... | nclq ''

# Count rows
nclq 'rows' data.ncl --count

# Filter rows (type auto-detected from data)
nclq 'rows' data.ncl --where 'score>10'
nclq 'rows' data.ncl --where agg_level=1 --where 'description~Revenue'

# Sort
nclq 'rows' data.ncl --sort-by score --desc --limit 3

# Unique values of a field
nclq 'rows' data.ncl --unique category

# Inspect structure
nclq data.ncl --list-fields
nclq data.ncl --list-fields --depth 3

# Project fields
nclq 'rows' data.ncl --fields id,name

# Limit output
nclq 'rows' data.ncl --limit 5

# JSON output
nclq 'rows' data.ncl --format json

# Raw string (no quotes)
nclq 'metadata' data.ncl --raw

# Compact single-line output
nclq 'std.array.first rows' data.ncl --compact

# Combined pipeline
nclq 'rows' data.ncl --where agg_level=1 --sort-by cogcs --fields cogcs,description --limit 10

# Cross-reference two files
nclq 'a.rows |> std.array.filter (fun r =>
       std.array.elem r.id (b.codes |> std.array.map (fun c => c.id)))' \
  -f a=data.ncl -f b=codes.ncl
```

## Flags

| Flag                                    | Purpose                                                        |
|-----------------------------------------|----------------------------------------------------------------|
| `--format `   | Output format (default: nickel)                                |
| `--fields `                  | Project only named fields from results                         |
| `--limit `                           | Truncate arrays to first N elements                            |
| `--raw`                                 | Strip quotes from string output                                |
| `--compact`                             | Single-line output                                             |
| `-f =`                      | Bind a file to a name (multi-file mode)                        |
| `--where `                   | Filter: field=val, field>val, field~substr (repeatable, ANDed) |
| `--sort-by `                     | Sort by field (type auto-detected from data)                   |
| `--desc`                                | Descending sort (use with --sort-by)                           |
| `--unique `                      | Extract unique values of a field                               |
| `--count`                               | Return count instead of data                                   |
| `--list-fields`                         | List field names of the result                                 |
| `--depth `                           | Depth for --list-fields (default: 1)                           |

## Pipeline Order

When multiple flags are combined, they apply in this fixed order regardless of CLI position:

**where → sort-by → unique → fields → limit → count**

`--list-fields` is a separate inspection mode (only `--where` composes with it).

## Exit Codes

| Code | Meaning                                         |
|------|--------------------------------------------------|
| 0    | Success                                          |
| 1    | Nickel evaluation error (stderr passed through)  |
| 2    | Invalid arguments / usage error                  |
| 127  | `nickel` not found on `$PATH`                    |

## Workflow

1. Inspect file structure: `nclq data.ncl --list-fields` or `--list-fields --depth 2`
2. Count rows: `nclq 'rows' data.ncl --count`
3. Filter: `nclq 'rows' data.ncl --where 'score>10'`
4. Project and limit: `--fields id,name --limit 10`
5. Use `--format json` when piping to `jq` or other tools
6. For complex queries, write the nickel expression directly

## Key Notes

- The expression is **standard nickel** — use `std.array.filter`, `std.array.map`, `|>`, etc.
- Use `nclq` instead of `nickel export | jq` — it's shorter and stays in the nickel world
- `nclq file.ncl` with no expression just dumps the file (defaults to `_file`)
- In single-file mode, top-level fields are bound directly (e.g., `rows`, `metadata`)
- In multi-file mode, access fields through the binding name (e.g., `data.rows`)
- `_file` is always available as the raw imported record in single-file mode
- `--where` auto-detects value types from data (numbers, strings, bools, enums)
- `--where` operators: `=` `!=` `>` `=` `<=` `~` (contains)
- Check for optional fields with `std.record.has_field "field_name" record`

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [LouLouLibs](https://github.com/LouLouLibs)
- **Source:** [LouLouLibs/claude-skills](https://github.com/LouLouLibs/claude-skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-louloulibs-claude-skills-nclq
- Seller: https://agentstack.voostack.com/s/louloulibs
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.