@proseql/cli

Command-line interface for ProseQL databases. Query, create, update, and manage your plain text database files from the terminal.

Install

# Run directly with npx
npx @proseql/cli --help

# Or install globally
npm install -g @proseql/cli

Quick Start

# Initialize a new project
proseql init

# Query a collection
proseql query books --where 'year > 1970' --limit 10

# Create an entity
proseql create books --data '{"title":"Dune","author":"Frank Herbert","year":1965}'

# Update an entity
proseql update books abc123 --set 'year=2025,title=New Title'

# Delete an entity
proseql delete books abc123 --force

Config Shape

New ProseQL configs use top-level collections plus sources. Collections define schemas and identity policy; sources define where the CLI reads and writes documents. Relative source paths are resolved relative to the config file. Document-source outbox paths are resolved under the source root.

import { Schema, type DatabaseConfig } from "@proseql/core"

const BookPayload = Schema.Struct({
  title: Schema.String,
  author: Schema.String,
  year: Schema.Number,
})

export default {
  collections: {
    books: {
      schema: BookPayload,
      id: { kind: "derivedFromKey", field: "id" },
      relationships: {},
    },
  },
  sources: [
    {
      id: "library",
      kind: "documents",
      root: "./data",
      include: "**/*.yaml",
      format: "yaml",
      collections: "all",
      outbox: "generated.yaml",
    },
  ],
} as const satisfies DatabaseConfig

Matching YAML files are top-level objects keyed by collection name, then record id:

books:
  dune:
    title: Dune
    author: Frank Herbert
    year: 1965

The id above is derived from the object key (dune); do not duplicate it inside the persisted payload.

Commands

init

Scaffold a new ProseQL project with config and data files.

proseql init
proseql init --format yaml
proseql init --format toml

Creates:

• proseql.config.ts with an example notes collection under collections
• a document source under sources with root: "./data" and outbox: "generated.<format>"
• data/notes.{json,yaml,toml} with sample object-keyed document-source data
• updates .gitignore to exclude the data directory (if in a git repo)

| Option | Description | |--------|-------------| | --format <fmt> | Data file format: json (default), yaml, toml |

query

Query a collection with filters, sorting, and pagination.

proseql query <collection> [options]

# Examples
proseql query books
proseql query books --where 'year > 1970'
proseql query books --where 'genre = sci-fi' --where 'year < 2000'
proseql query books --select 'title,author' --sort 'year:desc' --limit 5
proseql query books --json | jq '.[] | .title'

| Option | Description | |--------|-------------| | -w, --where <expr> | Filter expression (can be repeated) | | -s, --select <fields> | Comma-separated fields to include | | --sort <field:dir> | Sort by field (asc or desc) | | -l, --limit <n> | Limit number of results |

Filter expressions use the format field operator value:

• year > 1970
• genre = sci-fi
• title != "Old Title"
• rating >= 4.5

create

Create a new entity in a collection.

proseql create <collection> --data '<json>'

# Examples
proseql create books --data '{"title":"Neuromancer","author":"William Gibson","year":1984}'
proseql create notes --data '{"title":"Meeting notes","content":"..."}'

| Option | Description | |--------|-------------| | -d, --data <json> | JSON object containing the entity data (required) |

The created entity is printed to stdout. An ID is auto-generated if not provided.

update

Update an existing entity by ID.

proseql update <collection> <id> --set '<assignments>'

# Examples
proseql update books abc123 --set 'year=2025'
proseql update books abc123 --set 'year=2025,title=Updated Title'
proseql update notes xyz --set 'content=New content here'

| Option | Description | |--------|-------------| | --set <assignments> | Comma-separated field assignments (required) |

Values are automatically coerced: numbers become numbers, true/false become booleans.

delete

Delete an entity by ID.

proseql delete <collection> <id> [options]

# Examples
proseql delete books abc123
proseql delete books abc123 --force

| Option | Description | |--------|-------------| | -f, --force | Skip confirmation prompt |

Without --force, you'll be prompted to confirm the deletion.

collections

List all collections with entity counts and persistence locations.

proseql collections

# Output:
# name   count  file                                                   format
# books  42     document source 'library' (root: data, outbox: data/generated.yaml) yaml

describe

Show schema details for a collection.

proseql describe <collection>

# Examples
proseql describe books
proseql describe books --json

Displays:

• Field names, types, and required/optional status
• Indexed fields
• Unique constraints
• Relationships
• Search index configuration
• Schema version (if versioned)
• Append-only mode (if enabled)

stats

Show statistics for all collections. Document-source-backed collections report the source and outbox rather than a single collection file.

proseql stats

# Output:
# name   count  file                                                   format  size
# books  42     document source 'library' (root: data, outbox: data/generated.yaml) yaml    (document source)

Includes entity counts, persistence locations, formats, and file sizes when a collection has a single file. Document sources report (document source) because records can be spread across many files.

migrate

Run schema migrations.

# Show migration status
proseql migrate status

# Preview what would run (dry run)
proseql migrate --dry-run

# Execute pending migrations
proseql migrate
proseql migrate --force  # skip confirmation

| Option | Description | |--------|-------------| | --dry-run | Show what would be done without executing | | -f, --force | Skip confirmation prompt |

Migration status shows:

• Current file version vs target version
• Collections that need migration
• Number of migrations to apply

convert

Convert a single-file collection's data file to a different format.

proseql convert <collection> --to <format>

# Examples
proseql convert books --to yaml
proseql convert notes --to json
proseql convert config --to toml

| Option | Description | |--------|-------------| | --to <format> | Target format (required) |

Supported formats: json, yaml, toml, json5, jsonc, hjson, toon

The command works for single-file collection configs. It explicitly rejects document-source-backed collections because converting a merged multi-file source needs deliberate routing and outbox semantics.

Document-source behavior in CLI commands

• query reads the merged logical collection across all matching source files.
• create writes new records to the configured source outbox and flushes before exit.
• update and delete rewrite the record's origin file and flush before exit.
• Duplicate (collection, id) records across source files and unknown top-level collection keys fail loudly by default, with file/collection/id context in the error.
• unknownCollections: "preserve" can be used when non-ProseQL top-level data must survive rewrites.
• YAML comments and exact formatting are not preserved after CLI writes.

Global Options

| Option | Description | |--------|-------------| | -h, --help | Show help message | | -v, --version | Show version | | -c, --config <path> | Path to config file (default: auto-discover) | | --json | Output as JSON | | --yaml | Output as YAML | | --csv | Output as CSV |

Output Formats

All commands that return data support multiple output formats:

# Default: table format (human-readable)
proseql query books

# JSON (pipe to jq, etc.)
proseql query books --json

# YAML
proseql query books --yaml

# CSV (for spreadsheets)
proseql query books --csv

Table is the default. JSON is useful for scripting and piping to other tools.

Config Discovery

The CLI automatically discovers your config file by searching upward from the current directory:

1. proseql.config.ts
2. proseql.config.js
3. proseql.config.json

The first file found is used. Source roots are resolved relative to that config file. Override with --config:

proseql query books --config ./path/to/proseql.config.ts

Examples

Querying with filters and piping to jq

# Get all sci-fi books as JSON
proseql query books --where 'genre = sci-fi' --json

# Pipe to jq for further processing
proseql query books --json | jq '.[] | {title, year}'

# Count results
proseql query books --where 'year > 2000' --json | jq length

Batch operations with shell scripts

# Export all collections to JSON
for collection in $(proseql collections --json | jq -r '.[].name'); do
  proseql query "$collection" --json > "export-$collection.json"
done

Migration workflow

# Check what needs migrating
proseql migrate status

# Preview the changes
proseql migrate --dry-run

# Apply migrations
proseql migrate --force

Format conversion

# Convert from JSON to YAML for better readability
proseql convert books --to yaml

# Convert to TOML for config-like data
proseql convert settings --to toml

License

MIT