Configuration Management
Relevant source files
The following files were used as context for generating this wiki page:
Configuration Management provides the infrastructure for persisting user settings, provider credentials, and routing preferences. It ensures that the CLI behaves consistently across sessions by managing a central config.json file. The system prioritizes security by refusing to accept sensitive credentials through command-line arguments and enforces atomic file operations to prevent data corruption during concurrent writes.
Sources: packages/scoutline/tests/config-store.test.js:12-40, SECURITY.md
Core Storage Architecture
Scoutline stores its configuration in a dedicated directory. By default, the system uses ~/.scoutline, but you can override this location using the SCOUTLINE_CONFIG_DIR environment variable. The primary configuration file is named config.json.
Path Resolution Logic
The system resolves the configuration root directory through a prioritized search:
- Environment Override: It checks for
SCOUTLINE_CONFIG_DIR. - Default Location: It falls back to the
.scoutlinefolder in the user's home directory.
The diagram shows how the configuration root is determined, prioritizing explicit environment variables over default paths.
Sources: packages/scoutline/tests/config-store.test.js:14-38
Config Schema and Validation
The configuration follows a versioned schema to ensure compatibility between CLI updates. The current standard is version: 1.
Key Configuration Fields
| Field | Type | Description |
|---|---|---|
version | Number | Schema version (e.g., 1). |
providers | Object | Dictionary of provider-specific settings and API keys. |
routing | Object | Maps capabilities (search, crawl) to a prioritized list of provider IDs. |
fallbackEnabled | Boolean | Determines if the CLI automatically tries alternative providers on failure. |
journal | Boolean | Controls whether research activities are logged to the local journal. |
hintShown | Boolean | Tracks if onboarding hints have been displayed to the user. |
Sources: packages/scoutline/tests/config-store.test.js:46-76, packages/scoutline/tests/config-store.test.js:255-275
Validation and Error Handling
The readConfig function performs strict validation during the load process. It classifies malformed JSON as a CONFIGURATION_ERROR and throws an upgrade error if it encounters an unsupported schema version. Unknown providers found in the configuration file are ignored with a warning rather than causing a total load failure.
Sources: packages/scoutline/tests/config-store.test.js:84-118
CLI Interaction and Modification
The config command provides the interface for viewing and modifying settings. It supports several subcommands: get, set, unset, and list.
Set and Unset Operations
The setConfigValue helper performs an atomic read-modify-write operation. It verifies if a key is "settable" before attempting a change.
- Credential Protection: Paths containing sensitive info (like
providers.zai.apiKey) are flagged ascredentialand refuse modification via theconfig setcommand. Users must usescoutline initor environment variables for these. - Strict Parsing: Boolean fields only accept
trueorfalsestrings. Routing tables require a comma-separated list of valid provider IDs.
The sequence diagram illustrates the atomic modification process, including key validation and file locking.
Sources: packages/scoutline/tests/config-store.test.js:338-380, packages/scoutline/tests/config-store.test.js:450-480
Routing and Provider Selection
Routing allows users to define which providers are used for specific capabilities. For example, a user can route all search requests to tavily and brave.
Lenient Loading
The system uses lenient validation for routing tables at load time. If a routing entry contains an unknown provider ID or an invalid capability key, the system warns the user and drops that specific entry while keeping the rest of the configuration valid. This prevents a single typo in a routing list from breaking the entire CLI.
Science Routing Exclusion
Per design rulings, scholarly lookups (Science capability) are excluded from the routing table in the configuration file. These operations typically use keyless lookups (like arXiv or PubMed) or specific environment variables like OPENALEX_API_KEY and NCBI_API_KEY.
Sources: packages/scoutline/tests/config-store.test.js:280-315, packages/scoutline/tests/science-docs.test.js:154-170
Atomic Operations and Reliability
To prevent data loss, the configuration manager utilizes atomic write patterns.
- Atomic Replace: When writing
config.json, the system writes to a temporary file first and then renames it to the target. This ensures that a crash during the write process does not leave a half-written, corrupt configuration file. - Concurrency Locking: A file-based lock prevents multiple CLI instances from writing to the config simultaneously. If a lock cannot be acquired within a timeout, the system throws a
ConfigurationError. - Refuse-to-Empty Guard: The system refuses to overwrite a populated configuration file with an empty or significantly smaller payload if a backup exists. This protects against logic errors that might clear user settings.
- Backups: Significant mutations trigger the creation of a
config.json.bakfile to allow for manual recovery.
Sources: packages/scoutline/tests/config-store.test.js:195-230, packages/scoutline/tests/config-store.test.js:630-660
Conclusion
Configuration Management in Scoutline balances user flexibility with system robustness. By implementing atomic file operations and strict validation for sensitive fields, the system protects against both accidental corruption and security vulnerabilities. The separation of environment variables, configuration files, and the CLI command interface ensures a predictable hierarchy for resolving settings and credentials.