# jq - not supported# fxecho 'name: Ada' | fx --yaml '.name'# 1ls (auto-detects format)echo 'name: Ada' | 1ls '.name'
Convert between forms:
# shorten1ls --shorten '.filter(x => x > 1).map(x => x * 2)'# → .fl(x => x > 1).mp(x => x * 2)# expand1ls --expand '.fl(x => x > 1).mp(x => x * 2)'# → .filter(x => x > 1).map(x => x * 2)
Installation
# Using bun (or npm, pnpm, etc)# works in the commandline or the webbun add -g 1ls# Or via binaries. here you get a QuickJs build# Using Homebrew (macOS/Linux)brew install yowainwright/tap/1ls# Using curlcurl -fsSL https://raw.githubusercontent.com/yowainwright/1ls/main/scripts/install.sh | bash
TODO: bash and fish shell completions are not yet supported.
Quick Start
# Get a propertyecho '{"name": "John", "age": 30}' | 1ls '.name'# Output: "John"# Array operationsecho '[1, 2, 3, 4, 5]' | 1ls '.filter(x => x > 2)'# Output: [3, 4, 5]# Map with arrow functionsecho '[1, 2, 3]' | 1ls '.map(x => x * 2)'# Output: [2, 4, 6]# Chain operationsecho '[{"name": "Alice", "age": 30}, {"name": "Bob", "age": 25}]' | 1ls '.filter(x => x.age > 26).map(x => x.name)'# Output: ["Alice"]# Interactive mode - explore JSON with fuzzy search1ls readFile data.json# Opens interactive explorer with fuzzy search, arrow key navigation, and live preview
Examples
Interactive Mode
Explore JSON interactively with fuzzy search and build expressions with method discovery:
# Open interactive explorer from a file (automatic when no expression)1ls readFile data.json# Works with all supported formats1ls readFile config.yaml1ls readFile config.toml# For remote data, save to a file firstcurl https://api.github.com/users/github > /tmp/user.json1ls readFile /tmp/user.json# Or use an expression directly (non-interactive)1ls readFile data.json '.users.filter(x => x.active)'
Mode 1: Path Explorer
Navigate and search JSON paths:
Fuzzy search: Type to filter paths (e.g., "user.name" matches .users[0].name, .user.username, etc.)
Live preview: See values as you navigate
Type information: Shows String, Number, Array, Object, Boolean, or null
Build complex expressions with guided method selection:
Workflow:
Navigate to a path in Explorer mode → Press Tab
Type to fuzzy search methods → → to accept
Type to fuzzy search properties → → to complete
Repeat to chain methods
Press Enter to execute
Example Session:
1. Navigate to .users (Array) → Tab2. Type "fil" → → (accepts .filter(x => ...))3. Type "act" → → (completes with x.active, back to method selection)4. Type "map" → → (accepts .map(x => ...))5. Type "name" → → (completes with x.name)6. Enter → executes: .users.filter(x => x.active).map(x => x.name)
# Read from file1ls readFile data.json '.users.filter(x => x.active)'# List files1ls --list . --recursive --ext .json# Grep files1ls --grep "TODO" --find . --recursive# With line numbers1ls --grep "function" --find ./src --line-numbers
Shortcuts
# Use shortcuts for common operationsecho '[1, 2, 3]' | 1ls '.mp(x => x * 2)' # Short for .map()echo '[1, 2, 3]' | 1ls '.flt(x => x > 1)' # Short for .filter()echo '["a", "b"]' | 1ls '.jn(",")' # Short for .join()# Show all shortcuts1ls --shortcuts# Expand shortcuts1ls --expand ".mp(x => x * 2)" # Output: .map(x => x * 2)# Shorten expression1ls --shorten ".map(x => x * 2)" # Output: .mp(x => x * 2)
CLI Options
Basic Options
Option
Short
Description
--help
-h
Show help
--version
-v
Show version
--interactive
Interactive fuzzy search explorer
--raw
-r
Output raw strings, not JSON
--pretty
-p
Pretty print output (default)
--compact
-c
Compact single-line output
--type
-t
Show type of result
--slurp
-S
Read all inputs into an array
--null-input
-N
Use null as input (for generating data)
Format Options
Option
Description
Values
--format
Output format
json, yaml, csv, table
--input-format, -if
Input format
json, yaml, toml, csv, tsv, lines, text
File Operations
Option
Short
Description
readFile
Read JSON from file
--list
-l
List files in directory
--find
-f
Find files matching pattern
--grep
-g
Search for pattern in files
--recursive
-R
Recursive search
--ignore-case
-i
Case insensitive search
--line-numbers
-n
Show line numbers
--ext
Filter by extensions (comma-separated)
--max-depth
Maximum depth for recursive operations
Shortcut Operations
Option
Description
--shortcuts
Show all available shortcuts
--expand
Expand shortcuts to full syntax
--shorten
Convert to shortcut syntax
API Reference
Property Access
.property - Access object property
["property"] - Access property with brackets
.[index] - Array index access (negative indexes supported)
.[start:end] - Array slice
.[] - Array spread
jq-compatible Operators
.. - Recursive descent (collect all nested values)
.foo? - Optional access (returns null on error instead of failing)
.foo ?? default - Null coalescing (provide fallback for null/undefined)
# Find all JSON files and extract specific fields1ls --list ./data --recursive --ext .json | \ 1ls '.map(f => f.path)' | \ xargs -I {} sh -c 'echo {} && 1ls readFile {} ".version"'# Search for TODOs in code1ls --grep "TODO" --find ./src --recursive --line-numbers# Process multiple CSV filesfor file in *.csv; do echo "Processing $file" cat "$file" | 1ls --input-format csv '.filter(x => x.status === "active")'done
Environment Variables
NO_COLOR - Disable colored output
Performance
1ls is built with Bun and optimized for speed:
Fast JSON parsing and stringification
Minimal overhead for expression evaluation
Efficient streaming for large files
Native binary compilation
Development
# Clone the repositorygit clone https://github.com/yowainwright/1ls.gitcd 1ls# Install dependenciesbun install# Run testsbun test# Buildbun run build# Build binariesbun run build:binary:all