flapii CLI

The flapii CLI provides powerful tools for developing and debugging flAPI endpoints locally. It's designed for a tight feedback loop—validate configs, test templates, and inspect endpoints instantly without starting the server.

Installation

The flapii CLI comes bundled with flAPI:

# If you have the flAPI binary
$ ./flapi --help

# Or install globally
$ npm install -g @flapi/cli
$ flapii --help

Core Commands

Validate Endpoints

Check your endpoint configuration for errors:

$ flapii endpoints validate /customers/

✓ Configuration valid
✓ SQL template found: sqls/customers.sql
✓ Connection 'postgres' exists
✓ All validators configured correctly
✓ No syntax errors

Endpoint ready to use!

Common validation checks:

• YAML syntax is valid
• Required fields are present
• SQL template file exists
• Referenced connections are configured
• Validators are properly defined
• Parameter types are valid

Error example:

$ flapii endpoints validate /orders/

✗ Validation failed

Errors:
  1. SQL template not found: sqls/orders.sql
  2. Connection 'warehouse' not defined in config
  3. Parameter 'status' missing validator

Fix these issues and try again.

Expand Templates

See the exact SQL that will be executed with given parameters:

$ flapii templates expand /customers/ \
    --params '{"segment": "ENTERPRISE", "active": true}'

Expanded SQL:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
SELECT 
  customer_id,
  name,
  segment,
  created_at
FROM customers
WHERE active = true
  AND segment = 'ENTERPRISE'
ORDER BY created_at DESC
LIMIT 100;
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Parameters used:
  - segment: "ENTERPRISE"
  - active: true

Template: sqls/customers.sql

Without parameters:

$ flapii templates expand /customers/

Expanded SQL (no parameters):
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
SELECT 
  customer_id,
  name,
  segment,
  created_at
FROM customers
WHERE active = true
ORDER BY created_at DESC
LIMIT 100;
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Use cases:

• Debug Mustache template logic
• Verify parameter injection
• Test conditional SQL blocks
• Check for SQL injection vulnerabilities

List Endpoints

View all configured endpoints:

$ flapii endpoints list

Configured endpoints:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Path                  Method    Auth    Cache    MCP Tool
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
/customers/           GET       JWT     No       -
/orders/              GET       JWT     Yes      -
/campaign-stats/      GET       JWT     Yes      get_campaign_performance
/products/search/     GET       None    No       search_products
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Total: 4 endpoints
MCP tools: 2

Test Queries

Execute a query with parameters to see results:

$ flapii query run /customers/ \
    --params '{"segment": "ENTERPRISE"}' \
    --limit 5

Executing query...

Results (5 rows):
┌─────────────┬───────────────────┬────────────┬─────────────────────┐
│ customer_id │ name              │ segment    │ created_at          │
├─────────────┼───────────────────┼────────────┼─────────────────────┤
│ 1001        │ Acme Corp         │ ENTERPRISE │ 2024-01-15 10:23:45 │
│ 1002        │ TechStart Inc     │ ENTERPRISE │ 2024-01-16 14:30:22 │
│ 1003        │ Global Solutions  │ ENTERPRISE │ 2024-01-17 09:15:33 │
│ 1004        │ DataFlow Systems  │ ENTERPRISE │ 2024-01-18 11:45:10 │
│ 1005        │ Cloud Dynamics    │ ENTERPRISE │ 2024-01-19 16:20:55 │
└─────────────┴───────────────────┴────────────┴─────────────────────┘

Query time: 0.12s

Advanced Usage

Inspect Cache

View cache status and statistics:

$ flapii cache status

Cache Status:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Table                 Rows      Size     Last Refresh
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
campaign_stats        12,450    2.3 MB   5 minutes ago
product_catalog       50,123    8.7 MB   1 hour ago
customer_segments     8,901     1.2 MB   30 minutes ago
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Total cache size: 12.2 MB

Refresh Cache Manually

$ flapii cache refresh campaign_stats

Refreshing cache: campaign_stats
Source: bigquery-marketing
Query: campaigns_cache.sql

✓ Query executed (2.3s)
✓ 12,450 rows loaded
✓ Cache updated

New cache size: 2.3 MB

Validate All

Check all endpoints at once:

$ flapii validate --all

Validating all endpoints...

✓ /customers/           OK
✓ /orders/              OK
✗ /products/            Failed: Template not found
✓ /campaign-stats/      OK

Summary: 3 passed, 1 failed

Configuration Check

Verify your main configuration:

$ flapii config check

Checking flapi.yaml...

✓ Valid YAML syntax
✓ All required fields present
✓ All connections defined
✓ Template path exists: ./sqls
✓ DuckDB configuration valid

Configuration is valid!

Warnings:
  ⚠ No authentication configured for endpoint /public/
  ⚠ Cache refresh schedule may be too frequent for /products/

Development Workflow

Recommended Flow

# 1. Create endpoint configuration
$ vim sqls/new-endpoint.yaml

# 2. Create SQL template
$ vim sqls/new-endpoint.sql

# 3. Validate configuration
$ flapii endpoints validate /new-endpoint/

# 4. Test template expansion
$ flapii templates expand /new-endpoint/ \
    --params '{"test": "param"}'

# 5. Run test query
$ flapii query run /new-endpoint/ \
    --params '{"test": "param"}' \
    --limit 10

# 6. Start server
$ ./flapi -c config.yaml

Debugging Templates

When a template isn't working as expected:

# Step 1: Check basic expansion
$ flapii templates expand /endpoint/

# Step 2: Try with parameters
$ flapii templates expand /endpoint/ \
    --params '{"param1": "value1"}'

# Step 3: Test query execution
$ flapii query run /endpoint/ \
    --params '{"param1": "value1"}' \
    --debug

# Step 4: Check for SQL errors
$ flapii query explain /endpoint/ \
    --params '{"param1": "value1"}'

CI/CD Integration

GitHub Actions

name: Validate flAPI Endpoints

on: [push, pull_request]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      
      - name: Install flAPI
        run: |
          wget https://github.com/datazoode/flapi/releases/latest/flapi
          chmod +x flapi
      
      - name: Validate all endpoints
        run: ./flapi validate --all
      
      - name: Check configuration
        run: ./flapi config check

Pre-commit Hook

#!/bin/bash
# .git/hooks/pre-commit

echo "Validating flAPI configuration..."

./flapi validate --all

if [ $? -ne 0 ]; then
  echo "❌ Validation failed. Commit aborted."
  exit 1
fi

echo "✅ All endpoints valid"
exit 0

Configuration

The CLI reads from flapi.yaml by default, or you can specify a different config:

$ flapii --config /path/to/config.yaml endpoints list

Environment Variables

# Override config file location
export FLAPI_CONFIG=/path/to/config.yaml

# Set verbosity
export FLAPI_LOG_LEVEL=debug

# Use different DuckDB database
export FLAPI_DB_PATH=/tmp/flapi-dev.db

Common Patterns

Testing Parameter Validation

# Test with invalid parameter
$ flapii query run /customers/ \
    --params '{"id": "not-a-number"}'

✗ Validation failed
Parameter 'id' must be an integer

Checking MCP Tool Definitions

$ flapii mcp list

MCP Tools:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Name                          Endpoint
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
get_campaign_performance      /campaign-stats/
search_products               /products/search/
lookup_customer               /customers/lookup/
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

$ flapii mcp inspect get_campaign_performance

Tool: get_campaign_performance
Description: Retrieves marketing campaign performance metrics
Parameters:
  - country (string, optional): Two-letter country code
  - campaign_type (string, optional): Type of campaign
Output: JSON array of campaign statistics

VS Code Integration

The flapii CLI powers the VS Code extension. See VS Code Extension for details.

Troubleshooting

Command not found

$ flapii: command not found

# Solution: Use the flAPI binary directly
$ ./flapi --help

Configuration not found

$ flapii endpoints list
Error: Configuration file not found: flapi.yaml

# Solution: Specify config path
$ flapii --config /path/to/flapi.yaml endpoints list

Connection errors

$ flapii query run /endpoint/
Error: Failed to connect to database

# Solution: Check connection configuration
$ flapii config check

Next Steps

• VS Code Extension: Integrated development experience
• Configuration Service: Advanced configuration management
• Configuration Guide: Learn all configuration options
• SQL Templating: Master template syntax for testing
• Endpoints Overview: Configure and validate endpoints
• Build from Source: Compile flAPI locally
• Deployment Guide: Deploy to production

Need help? Join our GitHub Discussions.