Skip to main content

flapii CLI

flapii is the command-line client for the flAPI Configuration Service. It talks to a running flapi server over HTTP (/api/v1/_config/*) to inspect and manage endpoints, SQL templates, caches, and project settings at runtime — no restart required.

flapii is a separate binary from the flapi server. For the server's CLI flags (-c, -p, --log-level, --validate-config, --config-service, --config-service-token, --no-telemetry) and the flapi pack / info / unpack self-packaging subcommands, see the dedicated Server CLI reference.

Installation​

flapi (server) and flapii (CLI) are shipped together. Both binaries live inside the flapi-io PyPI wheel and inside the GitHub release archive for your platform.

pip install flapi-io
flapi  --help        # server
flapii --help        # CLI

Both flapi and flapii entry points are installed on your PATH by a single pip install. The package name is flapi-io because flapi is taken on PyPI — there is no separate flapii distribution.

Standalone binaries​

Each GitHub release ships pre-compiled archives that contain both binaries:

AssetContents
flapi-linux-amd64.tar.gzflapi (server) + flapii (CLI)
flapi-linux-arm64.tar.gzflapi + flapii
flapi-macos-arm64.tar.gzflapi + flapii
flapi-windows-amd64.zipflapi.exe + flapii.exe

Download from the Releases page, extract, and put both binaries on your PATH:

curl -L https://github.com/DataZooDE/flapi/releases/latest/download/flapi-linux-amd64.tar.gz \
  | tar xz
chmod +x flapi flapii
./flapii --help

Try without installing​

uvx --from flapi-io flapii --help
uvx --from flapi-io flapi  -c flapi.yaml     # run the server the same way

Talking to a server​

flapii needs a running flapi server with the Configuration Service enabled:

# Start the server with the config service API exposed
./flapi -c flapi.yaml --config-service --config-service-token "$FLAPI_CONFIG_SERVICE_TOKEN"

Point flapii at it via flags or environment variables:

export FLAPI_BASE_URL=http://localhost:8080
export FLAPI_CONFIG_SERVICE_TOKEN="your-token"

flapii ping
flapii endpoints list

Global Options​

The following flags work on every subcommand:

FlagDescriptionEnv var
-c, --config <path>Path to flapi.yaml (used to derive defaults like base URL)—
-u, --base-url <url>Base URL of the flapi serverFLAPI_BASE_URL
--auth-token <token>Bearer token for endpoint authenticationFLAPI_TOKEN
-t, --config-service-token <token>Token for the Configuration Service APIFLAPI_CONFIG_SERVICE_TOKEN
--timeout <seconds>HTTP request timeoutFLAPI_TIMEOUT
--retries <count>Number of retries for failed requestsFLAPI_RETRIES
--insecureDisable TLS certificate verification—
-o, --output <format>Output format: json (default) or table—
--json-style <style>JSON key casing: camel (default) or hyphen—
--debug-httpPrint HTTP request and response bodies—
-q, --quietSuppress non-error output—
-y, --yesAssume yes for confirmation prompts—

Additional environment variables read by the CLI:

  • FLAPI_GEMINI_KEY — Gemini API key used by flapii project init --ai and flapii endpoints wizard --ai.

Subcommands​

The CLI exposes the following command groups (verify with flapii --help):

ping​

flapii ping

Checks that the configured server is reachable and the token (if any) is accepted.

config​

Inspect and manage server-side configuration state.

flapii config show
flapii config validate
flapii config log-level get
flapii config log-level set debug
flapii config log-level list

project​

flapii project get                 # Read project metadata from the server
flapii project init                # Scaffold a new flapi project in the current directory
flapii project init my-api         # Scaffold into a new directory
flapii project init my-api --force --no-examples --advanced --ai

project init flags:

  • -f, --force — overwrite existing files
  • --skip-validation — skip post-scaffold config validation
  • --no-examples — only create directories and flapi.yaml
  • --advanced — include extra template files
  • --ai — use Gemini-assisted configuration (requires FLAPI_GEMINI_KEY)

endpoints​

flapii endpoints list
flapii endpoints get /customers
flapii endpoints create
flapii endpoints update /customers
flapii endpoints delete /customers
flapii endpoints validate /customers
flapii endpoints reload /customers
flapii endpoints wizard

endpoints reload <path> calls POST /api/v1/_config/endpoints/{slug}/reload to apply changes without a server restart.

templates​

flapii templates list
flapii templates get /customers
flapii templates update /customers
flapii templates expand /customers --params '{"id":"123"}'
flapii templates test /customers

cache​

flapii cache list
flapii cache get /customers
flapii cache update /customers
flapii cache template /customers
flapii cache update-template /customers
flapii cache refresh /customers

schema​

flapii schema get
flapii schema refresh
flapii schema connections
flapii schema tables

mcp​

flapii mcp tools list
flapii mcp tools get <name>
flapii mcp prompts list
flapii mcp prompts get <name>
flapii mcp resources list
flapii mcp resources get <name>

Common Workflows​

Validate an endpoint before reloading​

flapii endpoints validate /customers
flapii endpoints reload /customers

Inspect what SQL a template produces​

flapii templates expand /customers --params '{"segment":"ENTERPRISE"}'

Refresh a cached endpoint​

flapii cache refresh /customers
flapii cache get /customers --output table

Scaffold and run a new project​

flapii project init my-first-api
cd my-first-api
./flapi -c flapi.yaml

CI/CD Integration​

name: Validate flAPI configuration

on: [push, pull_request]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install flAPI
        run: |
          pip install flapi-io flapii

      - name: Validate configuration
        run: flapi --validate-config -c flapi.yaml

For per-endpoint validation against a running server, use flapii endpoints validate <path> in a job that first starts flapi --config-service in the background.

VS Code Integration​

A VS Code extension that wraps flapii is on the roadmap. See VS Code Extension for current status.

Server CLI​

The flapi server binary has its own reference page covering its flags, environment variables, and the pack / info / unpack self-packaging subcommands:

➡ Server CLI reference

That page is the canonical source for everything the flapi binary itself accepts; flapii (documented above) is the client tool that talks to a running server.

Troubleshooting​

flapii: command not found​

Install via pip install flapii or download a standalone binary from the Releases page.

Error: connection refused​

flapii could not reach the server. Check FLAPI_BASE_URL (default http://localhost:8080) and that the server is running with --config-service enabled.

401 Unauthorized from the Configuration Service​

Provide the token via -t/--config-service-token or FLAPI_CONFIG_SERVICE_TOKEN. The server requires either Authorization: Bearer <token> or X-Config-Token: <token>.

Next Steps​

Need help? Join our GitHub Discussions.

🍪 Cookie Settings