---
title: Configuration reference
description: YAML fields, paths, environment variables, and precedence.
---

## Paths

The default configuration path is `~/.moji/config.yaml`. Override it with
`MOJI_CONFIG`.

The default cache path is `$XDG_CACHE_HOME/moji` when `XDG_CACHE_HOME` is set,
or `~/.cache/moji` otherwise.

## Complete example

```yaml
download_dir: ~/Downloads/moji
github_token: ""
search_timeout_seconds: 15
cache_ttl_seconds: 3600
default_formats: [otf, ttf, woff2, dfont, pfb, pfm]
source_plugins: []

ranking:
  format: 3.0
  family_size: 4.0
  trusted: 1.5
  size_penalty: 0.5
  weight_bonus: 2.0
  variable_bonus: 1.5

rate_limits:
  github:
    timeout_seconds: 15
    retries: 2
  getfonts:
    timeout_seconds: 15
    retries: 1
  registry:
    timeout_seconds: 15
    retries: 1
  plugins:
    timeout_seconds: 20
    retries: 0
  websearch:
    timeout_seconds: 20
    retries: 0

providers:
  github:
    enabled: true
  getfonts:
    enabled: true
  registry:
    enabled: true
  plugins:
    enabled: true
  websearch:
    enabled: true
    instance: ""
```

## Fields

| Field | Type | Default | Meaning |
| --- | --- | --- | --- |
| `download_dir` | string | `~/Downloads/moji` | Destination for `get` and TUI downloads |
| `github_token` | string | empty | GitHub Code Search token |
| `search_timeout_seconds` | positive integer | 15 | Overall search deadline |
| `cache_ttl_seconds` | non-negative integer | 3600 | Cache lifetime; `0` disables cache hits |
| `default_formats` | string array | OTF, TTF, WOFF2, DFONT, PFB, PFM | Formats used without `--format` |
| `source_plugins` | string array | empty | Executable paths implementing the source plugin protocol |
| `ranking` | mapping | shown above | Relative score weights |
| `rate_limits` | mapping | shown above | Per-provider timeout and retry count |
| `providers` | mapping | shown above | Provider enablement and optional instance |

## Environment variables

| Variable | Meaning |
| --- | --- |
| `GITHUB_TOKEN` | GitHub token; takes precedence over the config token |
| `MOJI_CONFIG` | Alternate config path |
| `XDG_CACHE_HOME` | Alternate cache root |
| `EDITOR` | Program used by `moji config` |
| `NO_COLOR` | Disable styled terminal output |
| `TERM=dumb` | Disable styled terminal output |

Per-invocation flags override general config defaults. Provider availability
still depends on required credentials and instance settings. If no explicit
token is available, Moji uses an existing authenticated GitHub CLI session for
GitHub.com without saving its token.