> ## Documentation Index
> Fetch the complete documentation index at: https://gitquarry.micr.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Config And Credentials

> Understand config file fields, path resolution, host-scoped auth precedence, env vars, and insecure fallback rules.

# Config And Credentials

Gitquarry keeps config and credentials separate on purpose.

## Config Paths

By default, gitquarry uses the user config directory and stores data under:

```text theme={null}
<config-dir>/gitquarry/
```

Typical files:

* `config.toml`
* `credentials.toml` for the explicit insecure fallback path

On this machine, `gitquarry config path` returns:

```text theme={null}
/home/ubuntu/.config/gitquarry/config.toml
```

## `GITQUARRY_CONFIG_DIR`

You can override the config root:

```bash theme={null}
export GITQUARRY_CONFIG_DIR="$(mktemp -d)"
gitquarry config path
```

This is especially useful in tests, CI, and agent runs.

## Config Schema

Saved config fields:

* `host`
* `format`
* `limit`
* `progress`
* `color`

Current enums:

* `format`: `pretty|json|toon|compact|csv`
* `progress`: `auto|on|off`
* `color`: `auto|always|never`

Example:

```toml theme={null}
host = "github.com"
format = "json"
limit = 25
progress = "auto"
color = "auto"
```

## Intentionally Unsaved Defaults

Gitquarry does not persist defaults that would silently enable heavier search behavior.

That includes:

* `mode`
* `rank`
* `depth`
* `readme`
* `explain`
* blended weights
* discovery engine knobs

## Credential Resolution Order

For a given normalized host, gitquarry resolves credentials in this order:

1. host-specific env var
2. global `GITQUARRY_TOKEN`
3. saved secure credential
4. explicit insecure fallback file

Examples:

```bash theme={null}
export GITQUARRY_TOKEN_GITHUB_COM=ghp_example
export GITQUARRY_TOKEN=ghp_example
```

## Secure Storage

Secure OS storage is the default path.

On login, gitquarry verifies that the token can be read back before it reports success.

## Insecure Fallback

The fallback file is allowed only when:

```bash theme={null}
export GITQUARRY_ALLOW_INSECURE_STORAGE=1
```

Without that env var, a failed secure save returns `E_AUTH_STORAGE`.

On Unix-like systems, gitquarry restricts the config directory to owner-only permissions and does the same for the insecure credential file.

## Status And Logout Semantics

`auth status` reports the effective state for the current host.

If an environment override is active, that is reported separately from saved credential state.

`auth logout` removes saved credentials for the current host, including the opt-in insecure file.