CLI Command Reference
Relevant source files
The following files were used as context for generating this wiki page:
The SecretForge AI Command-Line Interface (CLI) serves as the primary tool for developers to interact with the secure secret management system. It provides a comprehensive suite of commands for project initialization, secret provisioning with AES-256-GCM encryption, and secure injection of environment variables into local development workflows.
The CLI is built using the Commander.js framework and integrates with a local SQLite storage layer for secret persistence and a CryptoProvider for cryptographic operations. It is designed to replace traditional, insecure .env file management with a robust, AI-aware workflow that detects required services and automates key provisioning.
Sources: README.md:12-25, packages/cli/src/sf.ts:1-10, PHASE1_IMPLEMENTATION.md:10-20
CLI Architecture and Entry Point
The CLI entry point is located in packages/cli/src/sf.ts. It utilizes the commander library to define the command hierarchy, options, and action handlers. The architecture follows a modular pattern where command logic is separated into specific handler files within the commands/ directory.
The diagram above illustrates how the sf.ts entry point routes user requests to specific command modules, which in turn interface with the shared Storage and Crypto providers.
Sources: packages/cli/src/sf.ts:7-78, PHASE1_IMPLEMENTATION.md:22-38
Primary Command Suite
Project Initialization (init)
The init command bootstraps a project for use with SecretForge. It performs three critical tasks: creating the .secretforge.json configuration file, setting up the local SQLite database, and ensuring an encryption key exists via the SECRETFORGE_ENCRYPTION_KEY environment variable.
| Option | Description |
|---|---|
--version | Displays current CLI version (1.0.0) |
--help | Displays help information for the init command |
Sources: packages/cli/src/sf.ts:13-22, PHASE1_IMPLEMENTATION.md:107-113
Secret Management (add)
The add command allows users to store new secrets with encryption. It can be run in an interactive mode or by passing a specific name. It requires the environment variable SECRETFORGE_ENCRYPTION_KEY to be set to a 32-byte base64 string to perform AES-256-GCM encryption before the secret is persisted to the database.
| Option | Argument | Description |
|---|---|---|
-e, --env | <environment> | Target environment: dev, staging, or prod |
-t, --tags | <tags> | Comma-separated list of tags for categorization |
Sources: packages/cli/src/sf.ts:25-36, PHASE1_IMPLEMENTATION.md:115-121
Viewing Secrets (list)
The list command provides a summary of stored secrets. Crucially, it hides the raw values, showing only metadata such as secret IDs, tags, and timestamps.
The metadata displayed includes the unique ID (prefixed with sec_), name, environment, and associated tags.
Sources: packages/cli/src/sf.ts:39-51, PHASE1_IMPLEMENTATION.md:123-128, SECURITY_SUMMARY.md:46-51
Local Injection (inject)
The inject command is used for local development. It decrypts secrets for a specific environment and writes them into a standard .env format file. This is the primary mechanism for moving secrets from the secure vault to the application runtime.
| Option | Required | Default | Description |
|---|---|---|---|
-e, --env | Yes | N/A | Environment to pull secrets from |
-f, --file | No | .env.<env> | Target output filename |
Sources: packages/cli/src/sf.ts:54-65, PHASE1_IMPLEMENTATION.md:130-136
Data Export (export)
The export command provides programmatic access to secrets, suitable for CI/CD pipelines. It supports multiple serialization formats.
| Format | Description |
|---|---|
env | Standard Key=Value format (Default) |
json | Structured JSON array of secrets |
yaml | YAML mapping for Kubernetes or configuration tools |
Sources: packages/cli/src/sf.ts:68-78, PHASE1_IMPLEMENTATION.md:138-144
Security and Cryptographic Integration
Every CLI command that handles secret values (add, inject, export) interacts with the CryptoProvider. The implementation uses AES-256-GCM, which provides both confidentiality and integrity verification via an authentication tag.
Database Schema Reference
The CLI manages an internal SQLite database (typically located at ~/.secretforge/<project>.db). The schema enforces uniqueness to prevent duplicate secrets within the same project/environment.
| Field | Type | Constraints |
|---|---|---|
id | TEXT | PRIMARY KEY (UUID v4) |
name | TEXT | NOT NULL |
project | TEXT | NOT NULL |
environment | TEXT | CHECK IN ('dev', 'staging', 'prod') |
value_encrypted | TEXT | NOT NULL |
tags | TEXT | DEFAULT '[]' (JSON Array) |
Sources: PHASE1_IMPLEMENTATION.md:40-54, SECURITY_SUMMARY.md:46-51
The SecretForge CLI provides a secure, developer-friendly alternative to plaintext environment management. By integrating AES-256-GCM encryption directly into the command workflow and utilizing a local-first SQLite storage model, it ensures that sensitive API keys remain protected at rest while remaining easily accessible for authorized local development and CI/CD injection.