fsqs

fsqs - Firestore Query CLI

Navigate and query Firestore like a filesystem.

Features

• Two modes: Interactive REPL or one-shot CLI commands
• Filesystem-like navigation: cd, ls, pwd commands
• Intuitive filtering: ls status=active age>18
• Multiple output formats: Table, JSON, YAML, CSV, JSON Lines
• Collection group queries: Query across all subcollections
• Bookmarks: Save and jump to frequently used paths
• Profiles: Switch between environments (prod, staging, etc.)
• Auto-detect project: From env vars or gcloud config
• Bulk export: Export entire collections with pagination
• Schema inference: Analyze collection structure
• Shell completions: bash, zsh, fish support
• Query history: View and replay past queries

Installation

npm install -g fsqs

Quick Start

# Start interactive REPL
fsqs

# Or run one-shot commands
fsqs ls users status=active --yaml
fsqs cat users/abc123
fsqs count users
fsqs export users output.jsonl --all
fsqs schema users

Two Ways to Use fsqs

1. CLI Mode (One-shot Commands)

Run commands directly from your terminal:

# List collections at root
fsqs ls

# List documents with filters
fsqs ls users status=active age>18

# Multiple output formats
fsqs ls users --json
fsqs ls users --yaml
fsqs ls users --csv
fsqs ls users --jsonl

# Write output to file
fsqs ls users --yaml --out users.yaml

# Pagination
fsqs ls users -n 100 --start-after lastDocId

# Show a specific document
fsqs cat users/abc123

# Count documents
fsqs count users status=active

# Aggregate queries
fsqs sum orders amount status=completed
fsqs avg products price category=electronics

# Explain query without executing
fsqs explain users status=active age>18 -o createdAt:desc

# Bulk export with pagination
fsqs export users users.jsonl --all

# Validate import file
fsqs validate data.jsonl

# Infer schema from collection
fsqs schema users -n 100

# View query history
fsqs history

# Generate shell completions
fsqs completions bash > ~/.bash_completion.d/fsqs
fsqs completions zsh > ~/.zsh/completions/_fsqs

2. REPL Mode (Interactive Shell)

Start an interactive session for exploration:

fsqs

This launches an interactive shell with:

• Command history (up/down arrows)
• Tab completion for commands and paths
• Persistent state (current path, output format)
• Bookmarks for quick navigation

fsqs:/> ls
users/
orders/
products/

fsqs:/> cd users
fsqs:/users> ls status=active -n 5
┌────────────┬────────┬───────────────┬──────┐
│ id         │ status │ email         │ age  │
├────────────┼────────┼───────────────┼──────┤
│ user1      │ active │ [e-mail]  │ 25   │
│ user2      │ active │ [e-mail]  │ 30   │
└────────────┴────────┴───────────────┴──────┘

fsqs:/users> .yaml
Output: YAML

fsqs:/users> cat user1
id: user1
email: [e-mail]
status: active
age: 25

fsqs:/users> exit

CLI Commands

Command	Description
fsqs ls [path] [filters...]	List collections or documents
fsqs cat <path>	Show a document
fsqs count <path> [filters...]	Count documents
fsqs sum <path> <field> [filters...]	Sum a numeric field
fsqs avg <path> <field> [filters...]	Average a numeric field
fsqs explain <path> [filters...]	Show query plan without executing
fsqs export <path> <file> [--all]	Export collection to file
fsqs validate <file>	Validate JSON/JSONL file for import
fsqs schema <path> [-n size]	Infer schema from sample
fsqs history [-n count]	Show query history
fsqs completions <shell>	Generate shell completions
fsqs	Start REPL mode

CLI Options

Flag	Description
-p, --project <id>	GCP project ID
-d, --database <id>	Firestore database ID
-n, --limit <number>	Max results (default: 10)
-o, --order <spec>	Order by field (e.g., name or age:desc)
-f, --fields <fields>	Fields to show (comma-separated, supports nested: user.name)
-j, --json	Output as JSON
-y, --yaml	Output as YAML
--csv	Output as CSV
--jsonl	Output as JSON Lines
-i, --id-only	Show only document IDs
--out <file>	Write output to file
--start-after <id>	Start after document ID (pagination)
--profile <name>	Use named profile from config
--plain	Plain output mode (no colors, no table)
--no-color	Disable colored output

Filter Syntax

field=value          # Equals
field!=value         # Not equals
field>value          # Greater than
field>=value         # Greater or equal
field<value          # Less than
field<=value         # Less or equal
field~prefix         # Starts with
field[]=value        # Array contains
nested.field=value   # Nested fields

Values are auto-typed:

• Numbers: age>18, price=99.99
• Booleans: active=true
• Null: deletedAt=null
• Dates: createdAt>2024-01-01
• Datetimes: updatedAt>2024-01-01T10:30:00
• Strings: status=active (no quotes needed)

REPL Commands

Navigation

Command	Description
cd <path>	Navigate to collection or document
cd ..	Go up one level
cd /	Go to root
pwd	Show current path

Querying

Command	Description
ls	List at current location
ls <filters>	List with filters
ls -n 50	Override limit
ls -o name:desc	Override order
ls -f name,email	Show only specific fields
ls -i	ID-only mode
ls -g orders	Collection group query
cat <id>	Show a document
count [filters]	Count documents
sum <field> [filters]	Sum a numeric field
avg <field> [filters]	Average a numeric field
explain [filters]	Show query plan without executing

Bookmarks

Command	Description
bookmark	List all bookmarks
bookmark add <name>	Save current path
bookmark del <name>	Delete a bookmark
go <name>	Jump to bookmark

Export

Command	Description
export <file>	Export last result (.json, .yaml, .csv, .jsonl)
copy	Copy last result to clipboard (JSON)

Settings

Command	Description
.table	Switch to table output
.json	Switch to JSON output
.yaml	Switch to YAML output
.csv	Switch to CSV output
.jsonl	Switch to JSON Lines output
.limit <n>	Set default limit
.profile <name>	Switch to named profile
.project <id>	Switch GCP project
.database <id>	Switch Firestore database
.connect	Show connection info

Configuration

Config File

Create ~/.fsqsrc to set defaults:

{
  "project": "my-project-id",
  "database": "(default)",
  "limit": 20,
  "format": "table"
}

Profiles

Define multiple environments in ~/.fsqsrc:

{
  "profiles": {
    "prod": {
      "project": "my-prod-project",
      "database": "(default)"
    },
    "staging": {
      "project": "my-staging-project",
      "database": "staging-db"
    }
  },
  "defaultProfile": "prod"
}

Use profiles:

fsqs --profile staging ls users

Or in REPL:

fsqs:/> .profile staging
Switched to profile: staging

Auto-detect Project

fsqs automatically detects your project from (in order):

• --project flag
• GOOGLE_CLOUD_PROJECT env var
• GCLOUD_PROJECT env var
• gcloud config get-value project
• Config file default

Pipe-friendly Mode

When output is piped, fsqs automatically:

• Disables colors
• Uses JSON Lines instead of table format

Force this behavior with --plain:

fsqs ls users --plain | jq '.email'

Machine-Readable Errors

When using --json or when output is piped, errors are returned as JSON:

{
  "error": true,
  "code": "DOCUMENT_NOT_FOUND",
  "message": "Document not found: 'users/invalid-id'",
  "details": { "path": "users/invalid-id" }
}

Error codes include:

• INVALID_PATH - Invalid path format
• COLLECTION_NOT_FOUND - Collection doesn't exist
• DOCUMENT_NOT_FOUND - Document doesn't exist
• INVALID_FILTER - Invalid filter syntax
• PERMISSION_DENIED - Firestore permission error
• UNAUTHENTICATED - Not logged in
• INDEX_REQUIRED - Composite index needed
• NETWORK_ERROR - Connection failed

Exit codes are specific to error types for scripting.

Shell Completions

Generate completions for your shell:

# Bash
fsqs completions bash > /etc/bash_completion.d/fsqs

# Zsh
fsqs completions zsh > ~/.zsh/completions/_fsqs

# Fish
fsqs completions fish > ~/.config/fish/completions/fsqs.fish

Authentication

Uses Google Cloud Application Default Credentials:

gcloud auth application-default login

Or use a service account key:

export GOOGLE_APPLICATION_CREDENTIALS=/path/to/key.json

License

MIT