Faz Docs

Environment variables, CLI flags, and the safety block in faz.yaml — every setting that changes faz at runtime.

faz reads its configuration from three places: faz.yaml, environment variables, and per-command CLI flags. This page is the cross-cutting reference for all three. For the full faz.yaml schema, see faz.yaml. For a per-command flag listing, see CLI.

Environment variables

Variable	Default	Notes
`FAZ_LOG_LEVEL`	`INFO`	Python logging level. Accepts `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`.
`FAZ_CONFIG`	(auto: `./faz.yaml`, then `./database.yaml`)	Explicit path to the config file. Overrides cwd-based lookup.
`FAZ_AUDIT_LOG`	`.faz/audit.jsonl` if `.faz/` exists, else off	Path to the audit JSONL file. Set to `""` (empty string) to disable file logging entirely; events still go to Python logging.

`FAZ_LOG_LEVEL`

Controls the verbosity of every log channel — connector lifecycle messages, safety pipeline decisions, audit summaries, errors. Set to DEBUG when reproducing a bug; the default INFO is right for normal use.

FAZ_LOG_LEVEL=DEBUG faz serve

FAZ_LOG_LEVEL=DEBUG uv run faz serve

FAZ_LOG_LEVEL=DEBUG python -m faz serve

`FAZ_CONFIG`

When you don't run faz from the directory containing your faz.yaml, set this to the absolute path:

FAZ_CONFIG=/etc/faz/prod.yaml faz serve

FAZ_CONFIG=/etc/faz/prod.yaml uv run faz serve

FAZ_CONFIG=/etc/faz/prod.yaml python -m faz serve

This is what faz mcp install bakes into the MCP client config so the spawned faz mcp process always finds the right file regardless of the client's working directory.

`FAZ_AUDIT_LOG`

By default, faz writes the audit log to .faz/audit.jsonl if a .faz/ directory exists in the working directory (which it does after faz init). To write somewhere else:

FAZ_AUDIT_LOG=/var/log/faz/audit.jsonl faz serve

FAZ_AUDIT_LOG=/var/log/faz/audit.jsonl uv run faz serve

FAZ_AUDIT_LOG=/var/log/faz/audit.jsonl python -m faz serve

To turn off file logging entirely (Python logging still receives audit events; useful for shipping to a SIEM via syslog or stdout collectors):

FAZ_AUDIT_LOG="" faz serve

FAZ_AUDIT_LOG="" uv run faz serve

FAZ_AUDIT_LOG="" python -m faz serve

The audit log format is documented on Audit log.

CLI flags

Per-command flags. The full per-command details are on CLI; this is the cross-cutting summary.

`faz serve`

Flag	Default	Notes
`--host`	`127.0.0.1`	Bind address. Anything except `127.0.0.1`, `::1`, `localhost` prints a warning about no built-in remote auth.
`--port`	`8787`	Bind port.

`faz init`

Flag	Default	Notes
`--force`	off	Overwrite an existing `faz.yaml` without asking. Without it, `faz init` refuses.

`faz mcp install`

Flag	Default	Notes
`--target`	`all`	One of `claude`, `cursor`, `openclaw`, `all`. Picks which client config to write.
`--dry-run`	off	Print the JSON that would be written, don't touch any files.
`--path`	(per target's standard location)	Override the auto-detected location and write to a specific file.

`faz logs`

Flag	Default	Notes
`--follow`, `-f`	off	Tail the file, printing new lines as appended. Survives log rotation by inode.
`--path`	`.faz/audit.jsonl`	Audit JSONL path. Override when `FAZ_AUDIT_LOG` points elsewhere.

faz query, faz test, faz policy, faz add-database, and faz mcp (no subcommand — runs the stdio server) take no flags.

The `safety:` block

The safety: block in faz.yaml controls the Guardrails stage of the safety pipeline. Two keys are enforced:

safety:
  max_rows_per_query: 1000      # default 1000 — applied as LIMIT/$limit/size
  query_timeout_seconds: 30     # default 30  — applied as maxTimeMS/timeout

These apply globally across every connector. There's no per-connector or per-table override yet — set the global value to whatever's safe for your largest table.

The faz init template ships with max_rows_per_query: 5000 and query_timeout_seconds: 30. The runtime fallback (when the key is absent) is 1000 and 30. Pick a value that fits your largest legitimate query.

Two roadmap keys appear in faz init's template but are not yet enforced:

queries_per_minute — per-instance rate limiting.
auto_block_sensitive (and sensitive_patterns) — column-level redaction overlay.

Setting them does nothing today; the parser preserves them for forward compatibility.

Precedence and reload

When a value can come from multiple places — the env var vs the CLI flag, for instance — the CLI flag wins. The order, lowest priority to highest:

Built-in defaults (e.g. 127.0.0.1 for serve --host).
faz.yaml values (for safety: keys).
Environment variables (FAZ_*).
CLI flags.

Configuration is read once at startup for faz serve and per-invocation for the one-shot CLI commands (query, policy, logs, etc.). There is no hot-reload — restart the process to pick up changes to faz.yaml or env vars.

faz.yaml — the full config schema.
CLI — every command and its flags.
Audit log — how FAZ_AUDIT_LOG affects what gets persisted.
Secrets — patterns for keeping passwords out of the config file.

Runtime Options