Skip to content

settings.md

Latest commit

 

History

History
144 lines (95 loc) · 4.26 KB

settings.md

File metadata and controls

144 lines (95 loc) · 4.26 KB

Settings

This article is about:

  • Configuration settings available in Hatchling
  • Settings categories and their purposes
  • Managing settings through the chat interface

Overview

Hatchling provides a comprehensive settings system to configure various aspects of the application including language model settings, file paths, tool behavior, and user interface preferences.

Settings Categories

The lists of settings was moved to settings reference

Managing Settings

Viewing Settings

List all available settings:

settings:list <setting>
  • Not giving any name will return the full list of settings.
  • Whatever you give will be matched to the closest setting existing.
    • If an exact match is found, it will stop there
    • if no exact match is found, it will derive a regex pattern from your input and return the list of all settings matching this pattern

Filter settings by category or name:

settings:list llm
settings:list model

Get a specific setting value:

settings:get llm:model
settings:get ui:language_code

Modifying Settings

Set a setting value:

settings:set llm:model mistral-large
settings:set ui:language_code fr --force-confirm

Using the flag --force-confirm will perform the changes immediately.

For protected settings, use the --force-protected flag:

settings:set llm:api_url /custom/path --force-protected

The protected settings can be found in the full list

Reset a setting to its default value:

settings:reset llm:api_url --force-protected
settings:reset ui:language_code --force-confirm

Import and Export

Export current settings to a file:

settings:export my-config.toml
settings:export backup.json
settings:export settings.yaml

Import settings from a file:

settings:import my-config.toml
settings:import backup.json --force-confirm --force-protected

Access Levels

Settings have different access levels that control how they can be modified:

  • Normal: Can be changed freely
  • Protected: Require --force flag to modify (sensitive settings)
  • Read-only: Cannot be modified (system-computed values)

Persistent Settings

Hatchling automatically saves and loads user settings to persist your preferences across sessions.

How It Works

  • On Startup: Settings are, by default, loaded from <path_to_hatchling_cache>/settings/hatchling_settings.toml
  • On Exit: Current settings are automatically saved to preserve changes
  • What's Saved: Only modifiable settings (excludes read-only settings like computed paths)

Configuration Directories

The cache and settings directories can be configured at install time via environment variables:

Environment Variable Purpose Default
HATCHLING_CACHE_DIR Main cache directory ~/.hatch
HATCHLING_SETTINGS_DIR Settings storage directory $HATCHLING_CACHE_DIR/settings

Note: These directories become read-only after first use to ensure consistency. In Docker environments, they are typically set via volume mounts.

Import/Export vs Persistent Settings

  • Persistent settings: Automatic save/load for session continuity
  • Import/Export: Manual operations for backup, sharing, or profile management
  • Read-only exclusion: By default, both persistent and export operations exclude read-only settings

Use settings:export filename --all to include read-only settings when creating complete configuration backups.

Command Reference

For detailed command syntax and examples, see the Chat Commands documentation.

Quick Reference

Task Command
List all settings settings:list
Get setting value settings:get category:name
Set setting value settings:set category:name value
Reset to default settings:reset category:name
Export settings settings:export filename
Export all settings settings:export filename --all
Import settings settings:import filename

Language Support

Hatchling supports multiple interface languages. See Language Support for details on changing the interface language and available translations.