CLI Configuration & Initialization
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The CLI Configuration & Initialization module is the foundational entry point for SecretForge AI. Its primary purpose is to establish a secure, local-first environment for secret management by setting up project-specific configurations, initializing local SQLite storage, and ensuring the presence of essential cryptographic keys. This process transitions a standard software project into a "SecretForge-enabled" workspace, allowing developers to manage sensitive API keys without committing them to version control.
The module operates through a specialized CLI binary (sf or secretforge) which orchestrates project analysis, interactive user prompts, and filesystem operations. It ensures that every project has a unique identity, a defined environment (dev, staging, or prod), and a secure database path for encrypted storage.
Sources: PHASE1_IMPLEMENTATION.md:1-12, packages/cli/src/sf.ts:1-10
Project Initialization Logic
Initialization is handled via the sf init command. This command performs a series of checks and setups to prepare the local environment. It first checks for an existing .secretforge.json configuration file to prevent accidental overwrites. If a configuration exists, the user is prompted to confirm an overwrite.
Initialization Flow
The initialization process follows a structured workflow involving project analysis and user input.
The flow ensures that a project name and default environment are defined before the local infrastructure is provisioned.
Sources: packages/cli/src/commands/init.ts:12-87, SYSTEM_EVALUATION.md:214-220
Dependency and Service Detection
During initialization, the CLI can automatically analyze the project's package.json to detect required API services based on project dependencies. This proactive analysis identifies services like Stripe, OpenAI, and AWS, allowing the CLI to suggest immediate secret provisioning.
| Detected Library | Service Identified |
|---|---|
stripe, @stripe/stripe-js | Stripe |
openai, @openai/api | OpenAI |
@anthropic-ai/sdk | Anthropic |
aws-sdk, @aws-sdk/client-s3 | AWS |
@supabase/supabase-js | Supabase |
Sources: packages/cli/src/index.ts:175-195, packages/mcp-server/src/index.ts:251-267
Configuration Management
Configuration is centralized through the ConfigManager class and the .secretforge.json file. This file acts as the project's manifest for secret management, mapping the project to its local database and environment settings.
.secretforge.json Structure
The configuration file is typically committed to version control and contains non-sensitive metadata about the SecretForge setup.
| Field | Type | Description |
|---|---|---|
version | string | The version of the SecretForge configuration schema. |
project | string | The unique name of the project. |
defaultEnvironment | string | The default environment (dev, staging, or prod) for commands. |
databasePath | string | Absolute path to the local SQLite database file. |
Sources: PHASE1_IMPLEMENTATION.md:116-125, packages/cli/src/cli/ConfigManager.ts:1-20
ConfigManager Operations
The ConfigManager is responsible for the lifecycle of the configuration file. It provides methods to initialize, read, and verify the existence of the project setup.
The databasePath is typically generated in a user-specific directory (e.g., ~/.secretforge/<project>.db) to ensure that the encrypted secrets are stored outside the project's source tree.
Sources: packages/cli/src/cli/ConfigManager.ts:1-40, PHASE1_IMPLEMENTATION.md:104-114
Cryptographic Initialization
A critical part of the initialization process is ensuring the presence of the SECRETFORGE_ENCRYPTION_KEY. This key is the root of trust for all AES-256-GCM encryption within the project.
Key Generation and Storage
If the environment variable SECRETFORGE_ENCRYPTION_KEY is not detected during sf init, the CLI generates a new 32-byte cryptographically secure key using crypto.randomBytes.
- Algorithm: AES-256-GCM
- Key Requirement: 32-byte (256-bit) Base64 encoded string.
- Storage Strategy: The key is NEVER stored in
.secretforge.jsonor the database. It must be provided as an environment variable to the CLI.
Sources: packages/cli/src/commands/init.ts:64-75, PHASE1_IMPLEMENTATION.md:143-155, SECURITY_SUMMARY.md:46-55
Sequence: Security Initialization
This sequence demonstrates how the CLI ensures the cryptographic provider is ready.
Conclusion
CLI Configuration & Initialization represents the setup phase of the SecretForge lifecycle. By combining automated dependency analysis, local SQLite database provisioning, and secure cryptographic key generation, it provides a "zero-config" experience while maintaining high security standards. This module ensures that all subsequent operations—adding, listing, or injecting secrets—function within a well-defined and secure project context.
Sources: README.md:20-30, PHASE1_IMPLEMENTATION.md:216-225