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 <HOST>	0.0.0.0	Bind address
--watch	off	Hot-reload when schema file changes
--introspection	off	Enable GraphQL introspection endpoint
--rest-path <PATH>	"/rest/v1"	REST URL path prefix. Overrides [rest].path in the schema TOML. Requires the rest-transport feature.
--dev-claims <JSON>	—	JSON string of default JWT claims for dev mode. Enables dev mode automatically. See Dev Mode.

fraiseql run serves all enabled transports (GraphQL, REST, gRPC) on the same port. There is no separate process or port for each transport. gRPC is distinguished from HTTP by content-type negotiation (application/grpc).

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.1.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 federation gateway

Start the federation gateway, routing GraphQL queries across multiple FraiseQL subgraphs. This is a subcommand of fraiseql federation.

fraiseql federation gateway [OPTIONS] <CONFIG>

Arguments:

• CONFIG — Path to gateway.toml configuration file (required)

Options:

Option	Default	Description
--check	off	Validate the gateway config and exit without starting the server

The gateway starts an axum HTTP server exposing three endpoints:

Endpoint	Description
/graphql	Federated GraphQL endpoint — routes queries to the appropriate subgraphs
/health	Health check — returns 200 OK when the gateway is running
/ready	Readiness check — returns 200 OK once all subgraphs have been introspected

At startup the gateway introspects each subgraph’s SDL, builds a type-level query plan (type → subgraph map), and merges responses from parallel subgraph requests.

Examples:

# Start the federation gateway
fraiseql federation gateway gateway.toml

# Validate config without starting
fraiseql federation gateway gateway.toml --check

Expected output:

$ fraiseql federation gateway gateway.toml
🍓 FraiseQL Gateway v2.1.0
   GraphQL endpoint: http://localhost:4000/graphql
   Health check:     http://localhost:4000/health
   Readiness check:  http://localhost:4000/ready
   Subgraphs:        users (http://localhost:4001/graphql)
                     orders (http://localhost:4002/graphql)
   Press Ctrl+C to stop

See the Federation Gateway guide for configuration format, query routing details, and migration from Apollo Router.

---

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 path (required, e.g. fraiseql.toml or schema.json)

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 (three-level check — see below)
--output-proto <PATH>	—	Write the auto-generated .proto file for gRPC clients. Requires the grpc-transport feature.
--features <LIST>	—	Comma-separated compile-time feature flags. Use rest-transport and grpc-transport to control which transports are included in the compiled output.

Examples:

# Compile from fraiseql.toml (INPUT is required)
fraiseql compile fraiseql.toml

# 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 fraiseql.toml --check

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

Expected output:

$ fraiseql compile fraiseql.toml --database "$DATABASE_URL"
✓ Schema validated (3 types, 2 inputs, 5 queries, 3 mutations)
✓ Database validation passed: all relations, columns, and JSON keys verified.
✓ Compiled to build/schema.compiled.json (0.4s)

Database validation levels

When --database is provided, the compiler connects to the live database and runs three levels of validation. All diagnostics are warnings — compilation never fails due to validation.

Level	What it checks	Example warning
L1	sql_source relation exists (tables, views, materialized views)	query 'users': sql_source 'v_user' does not exist in database
L2	JSONB column exists and has the correct type; relay cursor column exists	query 'users': column 'data' not found on 'v_user'
L3	JSONB keys match declared fields (samples rows from the view)	query 'users': JSON key 'email' not found in sampled data from 'v_user'.data

L1 catches typos and missing migrations. L2 catches schema drift (e.g. renamed columns). L3 is best-effort — it samples existing rows, so it may miss keys that only appear in some rows.

All four databases are supported: PostgreSQL, MySQL, SQLite, and SQL Server.

---

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
-l, --language <LANG>	Override language detection. Valid values: python, typescript, rust, java, kotlin, go, csharp, swift, scala
--recursive	Scan directories recursively

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

Examples:

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

# Explain a query from a file
fraiseql explain "query(\$id: ID!) { user(id: \$id) { name } }"

---

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

Examples:

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

---

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)

Examples:

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

---

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
-f, --format <FMT>	Output format: json, dot, mermaid, d2, console

Examples:

# Quick console view
fraiseql dependency-graph schema.compiled.json

# Graphviz DOT for rendering as a PNG
fraiseql dependency-graph schema.compiled.json -f dot > deps.dot
dot -Tpng deps.dot -o deps.png

# Mermaid diagram (paste into Markdown)
fraiseql dependency-graph schema.compiled.json -f 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
--federation	Run federation audit
--cost	Run cost audit
--cache	Run cache audit
--auth	Run auth audit
--compilation	Run compilation audit
--fail-on-critical	Exit non-zero on critical issues
--fail-on-warning	Exit non-zero on any warning
--verbose	Include detailed recommendations

Examples:

# Run all lint checks
fraiseql lint

# Auth audit only
fraiseql lint --auth

# Fail on any warning in CI
fraiseql lint --fail-on-warning

# Run cost and cache audits only
fraiseql lint --cost --cache --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
--check-unused	Warn on unused types
--check-cycles	Warn on circular dependencies

Examples:

# Basic structural validation
fraiseql validate schema.json

# Strict mode
fraiseql validate schema.json --strict

# Validate facts against a live database
fraiseql validate facts --database "$DATABASE_URL"

Expected output:

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

---

fraiseql doctor

Run diagnostic checks on your FraiseQL setup. Validates configuration, connectivity, and common setup issues.

fraiseql doctor [OPTIONS]

Checks performed:

1. Schema file exists and parses correctly
2. Schema version compatibility
3. TOML config validity
4. DATABASE_URL is set
5. Database is reachable
6. JWT secret configuration
7. Redis connectivity (if configured)
8. TLS certificate validity (if configured)
9. Cache + auth coherence

Options:

Option	Description
--config <CONFIG>	Path to fraiseql.toml config file (default: fraiseql.toml)
--schema <SCHEMA>	Path to schema.compiled.json (default: schema.compiled.json)
--database <DATABASE_URL>	Override DATABASE_URL for connectivity check
--json	Output as JSON (machine-readable)
-q, --quiet	Suppress output (exit code only)
-v, --verbose	Enable verbose logging
-d, --debug	Enable debug logging

Examples:

# Run all checks
fraiseql doctor

# Use custom paths
fraiseql doctor --config fraiseql.toml --schema schema.compiled.json

# Machine-readable output (for CI)
fraiseql doctor --json

# Silent mode — check exit code only
fraiseql doctor --quiet && echo "All checks passed"

---

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
-s, --schema <FILE>	Schema path (required)
-e, --entity <NAME>	Entity name to generate view for (required)
--view <NAME>	View name to generate
--refresh-strategy <STRATEGY>	Refresh strategy: trigger-based, scheduled

Examples:

# Generate a view for the User entity
fraiseql generate-views -s schema.json -e User --view va_users

# With trigger-based refresh strategy
fraiseql generate-views -s schema.json -e Order --view va_orders --refresh-strategy trigger-based

---

fraiseql introspect

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

fraiseql introspect facts [OPTIONS]

Options:

Option	Description
-d, --database <URL>	PostgreSQL connection string (required)
--format <FMT>	Output format: python, json

Examples:

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

# Emit a Python schema stub
fraiseql introspect facts --database "$DATABASE_URL" --format 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
-o, --output <FILE>	Output file path

---

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
--language <LANG>	SDK language: python, typescript, etc.
--database <TYPE>	Database type: postgres, mysql, etc.
--size <SIZE>	Project size: xs, s, m
--no-git	Skip git repository initialization

Example:

fraiseql init my-api --language python --database postgres

---

fraiseql migrate

Manage database migrations. This command wraps Confiture under the hood, so you do not need to install Confiture separately.

fraiseql migrate <SUBCOMMAND> [OPTIONS]

Subcommands:

Subcommand	Description
up	Apply all pending migrations
down	Roll back the last applied migration
status	Show which migrations have been applied and which are pending
create <NAME>	Create a new migration file pair (up/down SQL)

Options:

Option	Default	Description
--database <URL>	$DATABASE_URL	PostgreSQL connection string

Examples:

# Apply all pending migrations
fraiseql migrate up

# Roll back the last migration
fraiseql migrate down

# 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 federation graph

Export the federation entity graph from a compiled schema, showing entity ownership, key fields, and inter-service relationships.

fraiseql federation graph <SCHEMA> [OPTIONS]

Arguments:

• SCHEMA — Path to schema.compiled.json

Options:

Flag	Default	Description
-f, --format <FORMAT>	json	Output format: json, dot, mermaid

Examples:

# Export as JSON (default)
fraiseql federation graph schema.compiled.json

# Export as Mermaid diagram (paste into docs or GitHub)
fraiseql federation graph schema.compiled.json --format mermaid

# Export as Graphviz DOT for rendering
fraiseql federation graph schema.compiled.json --format dot | dot -Tsvg > graph.svg

---

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	Error (validation, compilation, or runtime failure)
2	Structural manifest error (only for validate-documents)

---

Environment Variables

Variable	Description
DATABASE_URL	PostgreSQL connection string (overrides [database] url)
FRAISEQL_PORT	Override the TCP port (integer). Equivalent to --port.
FRAISEQL_HOST	Override the bind address. Equivalent to --bind.
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
Start federation gateway	fraiseql federation gateway gateway.toml
Compile for production	fraiseql compile --check
Health check project	fraiseql doctor
Validate schema	fraiseql validate --strict
Validate trusted documents	fraiseql validate-documents trusted-documents.json
Check query cost	fraiseql cost "{ users { id } }"
Analyze schema	fraiseql analyze schema.compiled.json
Generate client types	fraiseql generate --language typescript
Export federation graph	fraiseql federation graph schema.compiled.json --format mermaid
Run migrations	fraiseql migrate up

CI/CD Integration

# Typical CI pipeline
fraiseql validate schema.json          # Validate configuration
fraiseql compile fraiseql.toml --check # Compile and validate schema
fraiseql lint --fail-on-warning        # Run all audits
fraiseql migrate up                    # Apply pending migrations
fraiseql run                           # Start server

Verify It Works

1. Check CLI is installed:

   fraiseql --version

   Expected output:

   fraiseql 2.1.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 }"

   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

Confiture

Confiture — Database schema management with Confiture