CLI Reference

Complete reference for the fraiseql command-line interface.

Installation

Cargo

cargo install fraiseql-cli

Homebrew

brew install fraiseql/tap/fraiseql

Binary

Download from GitHub Releases

---

Overview

FraiseQL ships as a single binary named fraiseql. It covers the full lifecycle in two phases:

1. Schema authoring — compile, extract, lint, validate, and analyze your schema
2. Runtime serving — compile and serve the GraphQL API in a single step with fraiseql run

fraiseql <SUBCOMMAND> [OPTIONS] [ARGUMENTS]

---

fraiseql run

Compile the schema and immediately start the GraphQL server. This is the command you will use most often — it compiles the schema in-memory (no disk artifact) and starts the HTTP server. With --watch, the server hot-reloads whenever the schema file changes.

fraiseql run [OPTIONS] [INPUT]

Arguments:

• INPUT — Schema file or fraiseql.toml (default: fraiseql.toml)

Options:

Option	Default	Description
--database <URL>	$DATABASE_URL	PostgreSQL connection string
--port <PORT>	8080	HTTP port to listen on
--bind <ADDR>	0.0.0.0	Bind address
--watch	off	Hot-reload when schema file changes
--introspection	off	Enable GraphQL introspection endpoint

Examples:

# Start with defaults (reads fraiseql.toml)
fraiseql run

# Specify database and config explicitly
fraiseql run fraiseql.toml --database postgres://localhost/mydb

# Development mode with hot-reload
fraiseql run --port 3000 --watch

# Enable introspection from a pre-compiled schema
fraiseql run schema.json --introspection

Expected output:

$ fraiseql run
🍓 FraiseQL v2.0.0
   GraphQL endpoint: http://localhost:8080/graphql
   Health check:     http://localhost:8080/health
   Schema:           3 types, 5 queries, 3 mutations
   Database:         PostgreSQL (pool: 2 connections)
   Press Ctrl+C to stop

Tip

Use --watch during development so the server restarts automatically when you edit the schema. In production, omit --watch and set --database via the DATABASE_URL environment variable.

---

fraiseql compile

Compile the schema to schema.compiled.json. Use this when you need the compiled artifact on disk — for example, to commit it to version control or to inspect it before deployment.

fraiseql compile [OPTIONS] [INPUT]

Arguments:

• INPUT — Schema file or directory (default: fraiseql.toml)

Options:

Option	Default	Description
-o, --output <FILE>	schema.compiled.json	Output file path
--check	off	Validate only; do not write output
--database <URL>	$DATABASE_URL	Validate against live database schema
-v, --verbose	off	Verbose output

Examples:

# Compile from fraiseql.toml
fraiseql compile

# Compile a specific schema file to a custom output path
fraiseql compile schema.json -o compiled.json

# Validate without writing (useful in CI)
fraiseql compile --check

# Validate against the database schema
fraiseql compile --check --database "$DATABASE_URL"

Expected output:

$ fraiseql compile
✓ Schema validated (3 types, 2 inputs, 5 queries, 3 mutations)
✓ SQL views verified against database
✓ Compiled to build/schema.compiled.json (0.4s)

Watch Mode

fraiseql compile --watch monitors schema files and recompiles on change:

• Watches: schema files, fraiseql.toml, db/schema/*.sql
• On file change: recompiles and reports errors without exiting
• Useful during development alongside fraiseql run --watch

# Recompile on every schema change
fraiseql compile --watch

# Serve with hot-reload (run handles watch internally)
fraiseql run --watch

---

fraiseql extract

Extract a FraiseQL schema from annotated source files. Supports Python, TypeScript, Go, and other languages that use FraiseQL annotations.

fraiseql extract [OPTIONS] [INPUT]

Arguments:

• INPUT — Source file or directory to scan for annotations

Options:

Option	Description
-o, --output <FILE>	Output schema file
--format <FMT>	Output format

Example:

# Extract schema from an annotated Python module
fraiseql extract src/models.py -o schema.json

---

Developer Tools

fraiseql explain

Show the SQL execution plan that FraiseQL generates for a given GraphQL query. Useful for understanding and optimizing query behavior.

fraiseql explain [OPTIONS] <QUERY>

Arguments:

• QUERY — GraphQL query string or path to a .graphql file

Options:

Option	Description
--schema <FILE>	Compiled schema (default: schema.compiled.json)
--variables <JSON>	Query variables as a JSON string
--format <FMT>	Output format: sql, plan, json

Examples:

# Show the generated SQL for a simple query
fraiseql explain "{ users { id name } }"

# With variables
fraiseql explain "query(\$id: ID!) { user(id: \$id) { name } }" \
    --variables '{"id": "123"}'

# Show the full execution plan from a query file
fraiseql explain query.graphql --format plan

---

fraiseql cost

Calculate the complexity score for a GraphQL query. Use this in CI to enforce query cost limits before deployment.

fraiseql cost [OPTIONS] <QUERY>

Arguments:

• QUERY — GraphQL query string or path to a .graphql file

Options:

Option	Description
--schema <FILE>	Compiled schema
--max-cost <N>	Exit with a non-zero code if cost exceeds N
--json	Machine-readable JSON output

Examples:

# Check cost of a deeply nested query
fraiseql cost "{ users { posts { comments { id } } } }"

# Enforce a cost budget in CI
fraiseql cost query.graphql --max-cost 100

---

fraiseql analyze

Analyze the schema for optimization opportunities across performance, security, federation, complexity, caching, and indexing categories.

fraiseql analyze [OPTIONS] [SCHEMA]

Arguments:

• SCHEMA — Compiled schema file (default: schema.compiled.json)

Options:

Option	Description
--category <CAT>	Filter: performance, security, federation, complexity, caching, indexing
--json	Machine-readable JSON output
--verbose	Include detailed recommendations

Examples:

# Full analysis with recommendations
fraiseql analyze schema.compiled.json

# Security-focused analysis
fraiseql analyze --category security --verbose

---

fraiseql dependency-graph

Visualize the type dependency graph of a compiled schema. Output can be piped into Graphviz, Mermaid, or D2 for rendering.

fraiseql dependency-graph [OPTIONS] [SCHEMA]

Arguments:

• SCHEMA — Compiled schema file (default: schema.compiled.json)

Options:

Option	Description
--format <FMT>	Output format: json, dot, mermaid, d2, console
--output <FILE>	Write output to file instead of stdout
--show-cycles	Highlight circular dependencies
--unused	Include unused types in the graph

Examples:

# Quick console view
fraiseql dependency-graph

# Graphviz DOT for rendering as a PNG
fraiseql dependency-graph --format dot -o deps.dot
dot -Tpng deps.dot -o deps.png

# Mermaid diagram (paste into Markdown)
fraiseql dependency-graph --format mermaid

---

fraiseql lint

Check the schema for design issues. Audits cover federation, cost, caching, authorization, and compilation correctness.

fraiseql lint [OPTIONS] [SCHEMA]

Arguments:

• SCHEMA — Schema file (default: fraiseql.toml or schema.compiled.json)

Options:

Option	Description
--audit <AUDIT>	Audit category: federation, cost, cache, auth, compilation
--fail-on <LEVEL>	Exit non-zero on: critical, warning, all
--fix	Auto-fix issues where possible
--json	Machine-readable JSON output

Examples:

# Run all lint checks
fraiseql lint

# Auth audit only, fail on any warning
fraiseql lint --audit auth --fail-on warning

# Auto-fix and verify in CI
fraiseql lint --fix --fail-on critical

---

fraiseql validate

Validate the structural correctness of a schema file. Optionally connects to the database to cross-check table and column references.

fraiseql validate [OPTIONS] [SCHEMA]

Arguments:

• SCHEMA — Schema file to validate

Options:

Option	Description
--strict	Treat warnings as errors
--database <URL>	Validate against a live database
--json	Machine-readable JSON output

Examples:

# Basic structural validation
fraiseql validate schema.json

# Strict mode with database cross-check
fraiseql validate --strict --database "$DATABASE_URL"

Expected output:

$ fraiseql validate
✓ fraiseql.toml is valid
✓ Database connection successful
✓ Schema compiles without errors
✓ All views exist in database

---

Code Generation

fraiseql generate-views

Generate SQL DDL statements for Arrow views derived from the compiled schema.

fraiseql generate-views [OPTIONS] [SCHEMA]

Arguments:

• SCHEMA — Compiled schema file

Options:

Option	Description
-o, --output <FILE>	Output SQL file
--refresh <STRATEGY>	Refresh strategy: trigger, scheduled
--include <PATTERNS>	Include only views matching a pattern (e.g. va_*, tv_*)

Examples:

# Generate all views to a SQL file
fraiseql generate-views -o views.sql

# Arrow views only, with trigger-based refresh
fraiseql generate-views --include "va_*" --refresh trigger -o arrow_views.sql

---

fraiseql introspect

Connect to a PostgreSQL database and discover fact tables, then emit a schema stub.

fraiseql introspect [OPTIONS]

Options:

Option	Description
--database <URL>	PostgreSQL connection string
--output <FORMAT>	Output format: python, json
--tables <PATTERN>	Table name pattern (default: tf_*)

Examples:

# Discover all fact tables in the database
fraiseql introspect --database "$DATABASE_URL"

# Emit a Python schema stub
fraiseql introspect --database "$DATABASE_URL" --output python > facts.py

---

fraiseql generate

Generate source files (client types, SDK stubs) from a compiled schema.

fraiseql generate [OPTIONS] [SCHEMA]

Arguments:

• SCHEMA — Compiled schema file

Options:

Option	Description
--language <LANG>	Target language for generated code
--output <DIR>	Output directory
--types-only	Generate type definitions only, no resolvers

---

Project Management

fraiseql init

Scaffold a new FraiseQL project with a starter fraiseql.toml, schema stub, and migration directory.

fraiseql init [OPTIONS] [NAME]

Arguments:

• NAME — Project name (default: current directory name)

Options:

Option	Description
--template <TPL>	Starter template
--database <URL>	Pre-fill database URL in config
--sdk <SDK>	Include SDK for a specific language

Example:

fraiseql init my-api --database postgres://localhost/mydb

---

fraiseql migrate

Manage database migrations via the bundled confiture migration tool.

fraiseql migrate <SUBCOMMAND> [OPTIONS]

Subcommands:

Subcommand	Description
up	Apply pending migrations
down	Roll back the last migration
status	Show applied and pending migrations
create <NAME>	Create a new migration file

Examples:

# Apply all pending migrations
fraiseql migrate up

# Check migration status
fraiseql migrate status

# Create a new migration
fraiseql migrate create add_user_table

---

fraiseql sbom

Generate a Software Bill of Materials for the schema, listing all types, fields, and their data lineage.

fraiseql sbom [OPTIONS] [SCHEMA]

Arguments:

• SCHEMA — Compiled schema file

---

fraiseql validate-documents

Validate a trusted documents manifest — checks that the file is well-formed JSON and that every key is a valid SHA-256 hex string matching its query body hash.

fraiseql validate-documents <MANIFEST>

Arguments:

• MANIFEST — Path to the trusted documents manifest JSON file

Examples:

# Validate the manifest before deploying
fraiseql validate-documents trusted-documents.json

# Use in CI to catch manifest errors early
fraiseql validate-documents ./manifests/trusted-documents.json && echo "Manifest OK"

Exit codes:

• 0 — Manifest is valid
• 1 — Manifest has structural errors or hash mismatches
• 2 — File not found or not valid JSON

See Trusted Documents for the manifest format.

---

Global Options

All commands support the following options:

Option	Description
-h, --help	Show help for the command
-V, --version	Print the fraiseql version

---

Exit Codes

Code	Meaning
0	Success
1	Validation or compilation error
2	Configuration error
3	Database connection error

---

Environment Variables

Variable	Description
DATABASE_URL	PostgreSQL connection string (overrides [database] url)
FRAISEQL_REQUIRE_REDIS=1	Refuse to start if PKCE state or rate limiting is using in-memory storage. Recommended for Kubernetes and other multi-replica deployments — catches misconfiguration at startup rather than at request time.
FRAISEQL_MCP_STDIO=1	Start the MCP (Model Context Protocol) server in stdio transport mode instead of HTTP. Used for Claude Desktop and other local MCP clients. Requires the server to be compiled with --features mcp.

---

Configuration File

Most commands read fraiseql.toml when no explicit input is provided. A minimal configuration:

[project]
name = "my-api"
version = "1.0.0"

[database]
url = "${DATABASE_URL}"

[server]
host = "0.0.0.0"
port = 8080

Pass the path explicitly to any command that accepts [INPUT] or [SCHEMA] if your config file is not named fraiseql.toml.

Quick Reference

Common Workflows

Task	Command
Start development server	fraiseql run --watch
Compile for production	fraiseql compile --check
Validate schema	fraiseql validate --strict
Check query cost	fraiseql cost query.graphql --max-cost 100
Analyze performance	fraiseql analyze --category performance
Generate client types	fraiseql generate --language typescript
Run migrations	fraiseql migrate up

CI/CD Integration

# Typical CI pipeline
fraiseql validate                 # Validate configuration
fraiseql compile --check          # Compile and validate schema
fraiseql lint --fail-on warning   # Run all audits
fraiseql test                     # Run tests (if configured)
fraiseql migrate up               # Apply migrations
fraiseql run                      # Start server

Verify It Works

1. Check CLI is installed:

   fraiseql --version

   Expected output:

   fraiseql 2.0.0

2. Validate a configuration file:

   fraiseql validate

   Expected output:

   ✓ fraiseql.toml is valid
   ✓ Database connection successful
   ✓ Schema compiles without errors

3. Compile a schema:

   fraiseql compile --check

   Expected output:

   ✓ Schema validated (3 types, 2 inputs, 5 queries, 3 mutations)
   ✓ SQL views verified against database
   ✓ Compilation successful

4. Test explain command:

   fraiseql explain "{ __typename }" --format sql

   Expected output:

   -- Generated SQL for query
   SELECT 'Query' as typename;

5. Start the server:

   fraiseql run &
   
   # Test the health endpoint
   curl http://localhost:8080/health

   Expected response:

   {"status": "ok"}

6. Run a lint check:

   fraiseql lint --fail-on warning

   Expected output:

   ✓ Federation audit passed
   ✓ Cost audit passed
   ✓ Cache audit passed
   ✓ Auth audit passed
   ✓ Compilation audit passed

Troubleshooting

Command Not Found

$ fraiseql
-bash: fraiseql: command not found

Solutions:

1. Ensure binary is in PATH: export PATH="$HOME/.cargo/bin:$PATH"
2. Reinstall: cargo install fraiseql-cli
3. Use full path: ~/.cargo/bin/fraiseql

Compilation Errors

$ fraiseql compile
Error: Schema compilation failed

Check:

1. Schema syntax is valid
2. All referenced types exist
3. Database connection is working (if using --database)
4. SQL views exist in database

Database Connection Errors

$ fraiseql run
Error: Cannot connect to database

Solutions:

1. Verify DATABASE_URL is set correctly
2. Check database is running: pg_isready -d $DATABASE_URL
3. Test connection manually: psql $DATABASE_URL -c "SELECT 1"

Port Already in Use

$ fraiseql run
Error: Address already in use (os error 48)

Solutions:

1. Use a different port: fraiseql run --port 8081
2. Find and kill the process using the port
3. Check what’s listening: lsof -i :8080

TOML Configuration

Configuration Reference — Full configuration reference

Deployment

Production Deployment — Production deployment guide