# Context Hub Configuration File Format: Complete YAML Schema and Examples

> Understand the Context Hub configuration file format. Explore the complete YAML schema and examples for `~/.chub/config.yaml` to manage your user-level settings effectively.

- Repository: [Andrew Ng/context-hub](https://github.com/andrewyng/context-hub)
- Tags: api-reference
- Published: 2026-03-20

---

**Context Hub stores user-level settings in a YAML file located at `~/.chub/config.yaml`, merging custom values with built-in defaults defined in [`cli/src/lib/config.js`](https://github.com/andrewyng/context-hub/blob/main/cli/src/lib/config.js).**

Context Hub, an open-source CLI tool maintained by Andrew Ng's team, relies on a structured configuration file to manage registry sources, output preferences, and telemetry settings. Understanding the Context Hub configuration file format is essential for customizing cache behavior, adding private documentation sources, and controlling data collection features.

## Configuration File Location and Loading

The configuration loader resides in [`cli/src/lib/config.js`](https://github.com/andrewyng/context-hub/blob/main/cli/src/lib/config.js), which attempts to read `~/.chub/config.yaml` at startup. When the file is absent, the system automatically creates it during the first-run welcome command, populated with the `DEFAULTS` constant defined in the same module.

The loader performs a shallow merge between the user-defined YAML map and the built-in defaults, meaning any omitted fields inherit their values from the `DEFAULTS` object.

## YAML Schema Specification

The configuration file consists of a top-level YAML map with the following optional fields:

### Core Settings

- **`output_dir`** (string): Directory where generated context files are written. Default: `.context`
- **`refresh_interval`** (integer): Cache TTL in seconds for fetched registries. Default: `21600` (6 hours)
- **`output_format`** (string): Selects between `human` (readable) or `json` (machine-readable) output. Default: `human`
- **`source`** (string): Comma-separated list of source names agents may access (e.g., `official,maintainer,community`). Default: `official,maintainer,community`

### Telemetry and Feedback Controls

- **`telemetry`** (boolean): Enables anonymous usage reporting to the telemetry endpoint. Default: `true`
- **`feedback`** (boolean): Enables the post-search thumbs-up/down prompt. Default: `true`
- **`telemetry_url`** (string): Remote endpoint receiving telemetry data. Default: `https://chub.telemetry.run/`

### Custom Registry Sources

The **`sources`** field accepts a list of objects defining external registries. Each entry requires:

- **`name`** (string): Unique identifier for the source
- Either **`url`** (string): Remote YAML registry URL, OR **`path`** (string): Local filesystem directory containing documentation

This structure supports both remote registry fetching and local "bring-your-own-data" (BYOD) workflows documented in [`docs/byod-guide.md`](https://github.com/andrewyng/context-hub/blob/main/docs/byod-guide.md).

## Practical Configuration Examples

### Minimal Configuration

An empty file or complete absence of [`config.yaml`](https://github.com/andrewyng/context-hub/blob/main/config.yaml) causes the CLI to rely entirely on internal defaults:

```bash

# No configuration file required for basic usage

chub search "python decorators"

```

### Customizing Cache TTL and Output Format

To extend the cache lifetime to 12 hours and force JSON output:

```yaml

# ~/.chub/config.yaml

refresh_interval: 43200
output_format: json

```

```bash
chub search "docker compose" --json

```

### Adding Local Documentation Sources (BYOD)

Reference local build output by specifying a `path` instead of a `url`:

```yaml

# ~/.chub/config.yaml

sources:
  - name: my-project
    path: /Users/alice/projects/my-docs/build

```

After updating the configuration, force a cache refresh to index the new source:

```bash
chub update
chub search "my-project authentication"

```

### Disabling Telemetry and Feedback

To opt out of anonymous reporting and post-search prompts:

```yaml

# ~/.chub/config.yaml

telemetry: false
feedback: false

```

## Validation and Schema Authority

The configuration schema is validated by the test suite in [`cli/tests/lib/config.test.js`](https://github.com/andrewyng/context-hub/blob/main/cli/tests/lib/config.test.js), which ensures that default values are correctly applied when fields are omitted. Authoritative documentation regarding the YAML structure appears in [`docs/design.md`](https://github.com/andrewyng/context-hub/blob/main/docs/design.md), while the runtime implementation—including the `DEFAULTS` constant and merge logic—resides in [`cli/src/lib/config.js`](https://github.com/andrewyng/context-hub/blob/main/cli/src/lib/config.js).

## Summary

- Context Hub uses **YAML format** for configuration stored at `~/.chub/config.yaml`
- The loader in [`cli/src/lib/config.js`](https://github.com/andrewyng/context-hub/blob/main/cli/src/lib/config.js) merges user settings with the `DEFAULTS` constant, applying built-in values for any omitted fields
- Key configurable areas include **output directories**, **cache TTL** (`refresh_interval`), **output formatting**, and **registry sources**
- The **`sources`** array supports both remote URLs and local filesystem paths for BYOD workflows
- Configuration changes take effect immediately, though registry updates may require `chub update` to refresh the cache

## Frequently Asked Questions

### What is the default location for the Context Hub configuration file?

The CLI expects the configuration file at `~/.chub/config.yaml` on Unix-like systems. If this file does not exist, the application creates it automatically during the first-run welcome sequence, initialized with default values from the `DEFAULTS` object in [`cli/src/lib/config.js`](https://github.com/andrewyng/context-hub/blob/main/cli/src/lib/config.js).

### Can I use Context Hub without creating a configuration file?

Yes. The tool functions without a configuration file by using the built-in `DEFAULTS` defined in [`cli/src/lib/config.js`](https://github.com/andrewyng/context-hub/blob/main/cli/src/lib/config.js). All fields are optional, and the CLI will use fallback values for `output_dir`, `refresh_interval`, `telemetry`, and other settings when no user configuration is present.

### How do I add my own documentation to Context Hub searches?

Add a local source entry to the `sources` list in your configuration file, specifying a `name` and a local `path` pointing to your documentation directory. Unlike remote sources that use a `url` field, local sources reference filesystem locations directly, enabling private documentation indexing as described in [`docs/byod-guide.md`](https://github.com/andrewyng/context-hub/blob/main/docs/byod-guide.md).

### What happens if I disable telemetry in the Context Hub configuration?

Setting `telemetry: false` in `~/.chub/config.yaml` prevents the CLI from sending anonymous usage data to the default endpoint at `https://chub.telemetry.run/`. This change takes effect immediately on the next command execution without requiring a restart or cache refresh.