# Configuration

Census supports TOML configuration files with a precedence chain.

## Precedence (highest wins)

1. CLI flags (`--api-key`, `--base-url`, etc.)
2. Environment variables (`CERTISIGMA_API_KEY`, `CERTISIGMA_BASE_URL`)
3. Project-level `.census.toml` (current directory or parent)
4. User-level `~/.config/certisigma-census/config.toml`
5. Built-in defaults

## Config File Locations

| Level | Path |
|-------|------|
| User | `~/.config/certisigma-census/config.toml` (or `$XDG_CONFIG_HOME`) |
| Project | `.census.toml` (walks up from current directory) |

## Creating a Config

```bash
# Create user-level config template
census config init

# Create project-level config
census config init --project

# View effective config (merged)
census config show

# Show config file locations
census config paths
```

## Config File Format

```toml
# CertiSigma Census configuration

# API key (or set CERTISIGMA_API_KEY env var)
# api_key = "cs_..."

# API base URL (default: https://api.certisigma.ch)
# base_url = "https://api.certisigma.ch"

# Default source label for attestations
# source = ""

[scan]
# include = ["*.pdf", "*.docx"]
# exclude = ["*.log", "*.tmp"]
# min_size = ""
# max_size = "1G"

[watch]
# debounce = 2.0
# batch_interval = 30.0
# on_delete = "ignore"
# polling = false
```

## Security

- API keys in config files are masked in `census config show` output
- Config files should have restrictive permissions (0600)
- Prefer environment variables for CI/CD pipelines

## CLI Reference

| Action | Description |
|--------|-------------|
| `show` | Display effective merged config (sensitive values masked) |
| `init` | Create a template config file |
| `paths` | Show config file locations and which exist |
| `--project` | Act on project `.census.toml` instead of user config |

## Python Compatibility

- Python 3.11+: uses built-in `tomllib`
- Python 3.10: uses `tomli` (automatically installed as dependency)
