### Setup SnapAI Environment

Source: https://github.com/betomoedano/snapai/blob/main/CONTRIBUTING.md

Commands to clone the repository, install dependencies, and verify the CLI installation.

```bash
# Clone the repository
git clone https://github.com/betomoedano/snapai.git
cd snapai

# Install dependencies
pnpm install

# Build the project
pnpm run build

# Test the CLI
./bin/dev.js --help
```

--------------------------------

### Initial SnapAI Project Setup

Source: https://github.com/betomoedano/snapai/blob/main/DEV_SETUP.md

Install dependencies and build the project for the first time. This is a prerequisite for running development commands.

```bash
cd /Users/beto/Desktop/apps/snapai
pnpm install
pnpm run build
```

--------------------------------

### Configuration File Example

Source: https://github.com/betomoedano/snapai/blob/main/_autodocs/api-reference-config-service.md

This is an example of the configuration file format, which is a JSON object. It is written with 2-space indentation for readability. The file is only updated when set(), setConfig(), or get() is called.

```json
{
  "openai_api_key": "sk-proj-...",
  "google_api_key": "AIzaSy...",
  "default_output_path": "./assets"
}
```

--------------------------------

### Install SnapAI

Source: https://github.com/betomoedano/snapai/blob/main/_autodocs/README.md

Clone the repository, navigate to the directory, install dependencies, and build the project.

```bash
git clone https://github.com/betomoedano/snapai.git
cd snapai
pnpm install
pnpm run build
```

--------------------------------

### Execute ConfigCommand Example

Source: https://github.com/betomoedano/snapai/blob/main/_autodocs/api-reference-config-command.md

Example of how to instantiate and run the ConfigCommand programmatically. Ensure to slice process.argv correctly.

```typescript
const cmd = new ConfigCommand(process.argv.slice(2), { root: process.cwd() });
await cmd.run();
```

--------------------------------

### Clone and Install Snapai Project

Source: https://github.com/betomoedano/snapai/blob/main/README.md

Use these commands to clone the repository, install dependencies, build the project, and view help for the development script.

```bash
git clone https://github.com/betomoedano/snapai.git
cd snapai && pnpm install && pnpm run build
./bin/dev.js --help
```

--------------------------------

### GitHub Actions Workflow for Snapai

Source: https://github.com/betomoedano/snapai/blob/main/_autodocs/configuration.md

Example GitHub Actions workflow to set up Node.js, install Snapai, and generate icons using environment secrets for API keys.

```yaml
name: Generate Icons
on: [push]

jobs:
  generate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '18'

      - name: Generate app icon
        env:
          SNAPAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
        run: npx snapai icon --prompt "minimalist weather app"

      - name: Upload icons
        uses: actions/upload-artifact@v3
        with:
          name: icons
          path: ./assets/
```

--------------------------------

### IconGenerationOptions Example

Source: https://github.com/betomoedano/snapai/blob/main/_autodocs/types.md

An example of setting up options for icon generation. This configuration specifies a prompt, model, quality, background, and output format.

```typescript
const options: IconGenerationOptions = {
  prompt: "minimalist weather app icon...",
  model: "gpt-1.5",
  quality: "high",
  background: "transparent",
  outputFormat: "png",
  numImages: 1,
  moderation: "auto",
};
```

--------------------------------

### Install SnapAI Globally

Source: https://github.com/betomoedano/snapai/blob/main/README.md

Install the SnapAI CLI globally using npm. This allows you to run snapai commands from any directory.

```bash
npm install -g snapai
```

--------------------------------

### Running the IconCommand

Source: https://github.com/betomoedano/snapai/blob/main/_autodocs/api-reference-icon-command.md

Example of how to instantiate and run the IconCommand programmatically.

```typescript
const cmd = new IconCommand(process.argv.slice(2), { root: process.cwd() });
await cmd.run();
```

--------------------------------

### Local Development with .env File for Snapai

Source: https://github.com/betomoedano/snapai/blob/main/_autodocs/configuration.md

Example `.env` file to store API keys for local development. Load these variables before running Snapai commands.

```bash
# .env (DO NOT COMMIT)
SNAPAI_API_KEY=sk-proj-xyz...
SNAPAI_GOOGLE_API_KEY=AIzaSy...
```

--------------------------------

### GitHub Actions Example for Icon Generation

Source: https://github.com/betomoedano/snapai/blob/main/README.md

Example of how to configure environment secrets in GitHub Actions to generate an app icon using Snapai.

```yaml
- name: Generate app icon
  run: npx snapai icon --prompt "minimalist weather app with sun and cloud" --output ./assets/icons
  env:
    SNAPAI_API_KEY: ${{ secrets.SNAPAI_API_KEY }}
```

--------------------------------

### Example Usage of buildFinalIconPrompt

Source: https://github.com/betomoedano/snapai/blob/main/_autodocs/api-reference-prompt-builders.md

Demonstrates how to use the `buildFinalIconPrompt` function with specific parameters to generate a prompt for an icon. The output is a multi-layer prompt with enhancements and style constraints.

```typescript
const finalPrompt = buildFinalIconPrompt({
  prompt: "calculator app",
  style: "minimalism",
  useIconWords: false,
  rawPrompt: false
});

// Returns multi-layer prompt with enhancement + style constraints
```

--------------------------------

### ConfigData Example

Source: https://github.com/betomoedano/snapai/blob/main/_autodocs/types.md

Illustrates how to define a configuration object conforming to the ConfigData interface. API keys are sensitive and should be handled securely.

```typescript
const config: ConfigData = {
  openai_api_key: "sk-proj-xyz...",
  google_api_key: "AIzaSy...",
  default_output_path: "./assets/icons"
};
```

--------------------------------

### Get All Configuration

Source: https://github.com/betomoedano/snapai/blob/main/_autodocs/api-reference-config-service.md

Reads the entire configuration from disk. If the file does not exist or is corrupted, it returns an empty object gracefully without throwing errors.

```typescript
static async getConfig(): Promise<ConfigData>

Reads the entire configuration file from disk. Creates an empty config file if it does not exist.

**Returns:** `Promise<ConfigData>` — parsed configuration object

**Behavior:**
- If config file exists and is valid JSON: returns parsed object
- If config file does not exist: creates empty file and returns `{}`
- If config file is corrupted (invalid JSON): catches error and returns `{}`

**Throws:** Never throws; errors are caught and handled gracefully

**Example:**
```typescript
const config = await ConfigService.getConfig();
console.log(config.openai_api_key); // undefined (if not set)
```
```

--------------------------------

### Raw Prompt with Style Constraint Example

Source: https://github.com/betomoedano/snapai/blob/main/_autodocs/api-reference-prompt-builders.md

Shows the output format when `rawPrompt` is `true` and a style is provided. The user's prompt is combined with the style as a dominant constraint.

```plaintext
STYLE PRESET (dominant): minimalism
Style directive (must dominate all decisions): [style-specific guidance]

User prompt: minimalist calculator icon
```

--------------------------------

### Generate Banking App Icon

Source: https://github.com/betomoedano/snapai/blob/main/README.md

Create a premium banking app icon with a shield and checkmark. This example uses the gpt-1.5 model.

```bash
npx snapai icon --prompt "premium banking app, shield + checkmark, clean gradients" --model gpt-1.5
```

--------------------------------

### Run SnapAI without Installation

Source: https://github.com/betomoedano/snapai/blob/main/README.md

Execute SnapAI commands directly using npx without a global installation. This is useful for trying out the tool or running it occasionally.

```bash
npx snapai --help
```

--------------------------------

### Build Final Icon Prompt Example

Source: https://github.com/betomoedano/snapai/blob/main/_autodocs/api-reference-prompt-builders.md

Demonstrates the construction of a final prompt for an icon, incorporating style and other parameters. This is used to generate multi-layer prompts for image generation models.

```typescript
// User runs:
// snapai icon --prompt "weather app" --style minimalism

const finalPrompt = buildFinalIconPrompt({
  prompt: "weather app",
  style: "minimalism",
  useIconWords: false,
  rawPrompt: false
});

// Result: Multi-layer prompt
// Layer 1: Concept guidance (archetype, material, composition)
// Layer 2: Technical constraints (size, fill %, safe areas)
// Layer 3: Style system (minimalism as dominant constraint)
//   - "Extreme reduction for clarity and function..."
//   - "Mandatory: max 3 colors, readable at small sizes"
//   - "Forbidden: gradients, shadows, 3D effects"
```

--------------------------------

### Raw Prompt Mode Example

Source: https://github.com/betomoedano/snapai/blob/main/_autodocs/api-reference-prompt-builders.md

Illustrates the output when `rawPrompt` is set to `true` and no style is provided. The user's prompt is sent literally without any SnapAI enhancements.

```typescript
// User's exact text
"minimalist calculator icon with blue and white colors"
```

--------------------------------

### Verify Project Dependencies

Source: https://github.com/betomoedano/snapai/blob/main/DEV_SETUP.md

Ensure all project dependencies are correctly installed by checking the `package.json` and the `node_modules` directory. This can be done by building the project or inspecting dependencies directly.

```bash
# Check if all deps are installed
pnpm run build
node -e "console.log(require('./package.json').dependencies)"
```

--------------------------------

### Generate 3D Star Icon with GPT Image 2

Source: https://github.com/betomoedano/snapai/blob/main/README.md

Generate a minimalist 3D star icon with soft glossy plastic. This example uses the 'gpt-image-2' model.

```bash
npx snapai icon --prompt "Minimal 3D star icon, soft glossy plastic, clean lighting, centered, square, no text" --model gpt-image-2
```

--------------------------------

### Generate Music Player App Icon

Source: https://github.com/betomoedano/snapai/blob/main/README.md

Generate an abstract music player app icon with clean shapes. This example uses the 'banana' model.

```bash
npx snapai icon --prompt "music player app, abstract sound wave, clean shapes" --model banana
```

--------------------------------

### get

Source: https://github.com/betomoedano/snapai/blob/main/_autodocs/api-reference-config-service.md

Reads a single configuration key from disk. This method provides type safety by ensuring only valid configuration keys are accessed.

```APIDOC
## get

### Description
Reads a single configuration key from disk. This method provides type safety by ensuring only valid configuration keys are accessed.

### Method
`static async`

### Parameters
#### Path Parameters
- **key** (`K extends keyof ConfigData`) - Required - Configuration key: `"openai_api_key"`, `"google_api_key"`, or `"default_output_path"`

### Returns
`Promise<ConfigData[K]>` — value of the key (or `undefined` if not set)

### Example
```typescript
const apiKey = await ConfigService.get("openai_api_key");
```
```

--------------------------------

### GitLab CI Configuration for Snapai

Source: https://github.com/betomoedano/snapai/blob/main/_autodocs/configuration.md

GitLab CI configuration to install Snapai and generate icons, using environment variables for API keys and defining artifacts.

```yaml
generate_icon:
  image: node:18
  script:
    - npm install -g snapai
    - snapai icon --prompt "minimalist weather app"
  artifacts:
    paths:
      - assets/
  env:
    SNAPAI_API_KEY: $OPENAI_API_KEY
```

--------------------------------

### Shell Aliases for SnapAI

Source: https://github.com/betomoedano/snapai/blob/main/DEV_SETUP.md

Add these aliases to your shell profile for quick access to SnapAI development commands. Ensure the path '/Users/beto/Desktop/apps/snapai' is correct for your setup.

```bash
# Add to ~/.zshrc or ~/.bashrc
alias snapai-watch="cd /Users/beto/Desktop/apps/snapai && pnpm run dev"
alias snapai-dev="cd /Users/beto/Desktop/apps/snapai && ./bin/dev.js"
alias snapai-build="cd /Users/beto/Desktop/apps/snapai && pnpm run build && node dist/index.js"
```

--------------------------------

### Generate 3D Crystal Gem Icon with GPT Image 2

Source: https://github.com/betomoedano/snapai/blob/main/README.md

Generate a tiny 3D crystal gem icon with faceted details. This example utilizes the 'gpt-image-2' model.

```bash
npx snapai icon --prompt "Tiny 3D crystal gem, faceted, glassy highlights, minimal, centered on plain background" --model gpt-image-2
```

--------------------------------

### Snapai API Key Resolution Logic

Source: https://github.com/betomoedano/snapai/blob/main/_autodocs/README.md

Visualizes the priority order for resolving API keys, starting from CLI flags and falling back to environment variables and configuration files.

```mermaid
graph TD
    A[IconCommand: --openai-api-key?] -->|if set, use it|
    B(Environment: SNAPAI_API_KEY?)
    B -->|if set, use it|
    C(Environment: OPENAI_API_KEY?)
    C -->|if set, use it|
    D(Config file: openai_api_key?)
    D -->|if set, use it|
    E(Error: API key not configured)
    A -->|otherwise|
    B -->|otherwise|
    C -->|otherwise|
    D -->|otherwise|
    E
```

--------------------------------

### One-off SnapAI Build and Test

Source: https://github.com/betomoedano/snapai/blob/main/DEV_SETUP.md

Build the project and immediately test a command, such as displaying help information. This is useful for quick checks without watch mode.

```bash
pnpm run build && ./bin/dev.js --help
```

--------------------------------

### Promote beta to stable

Source: https://github.com/betomoedano/snapai/blob/main/PUBLISHING_GUIDE.md

Bump the version to stable after successful beta testing.

```bash
# Bump to the stable version (e.g. 1.2.0-beta.3 -> 1.2.0)
npm version minor

# Push and create a regular (non-pre-release) GitHub Release
git push && git push --tags
```

--------------------------------

### Configure Snapai with API Keys (Local)

Source: https://github.com/betomoedano/snapai/blob/main/_autodocs/configuration.md

Set your OpenAI and Google API keys using the `snapai config` command. This is recommended for local development to persist your configuration.

```bash
snapai config --openai-api-key sk-proj-xyz...
snapai config --google-api-key AIzaSy...
snapai config --show
```

--------------------------------

### Read Configuration with ConfigService

Source: https://github.com/betomoedano/snapai/blob/main/_autodocs/api-reference-config-service.md

Retrieve all configuration settings using getConfig, or access individual keys with get. The get method supports type safety and provides a fallback option.

```typescript
// Read all configuration
const config = await ConfigService.getConfig();
console.log(config); // { openai_api_key: "$...

// Read single key with type safety
const apiKey = await ConfigService.get('openai_api_key');
console.log(apiKey); // "$..." or undefined

// Read with fallback
const apiKey = await ConfigService.get('openai_api_key') ?? 'default';
```

--------------------------------

### Build and Release Commands

Source: https://github.com/betomoedano/snapai/blob/main/_autodocs/README.md

Commands for building, bundling, testing, tagging, and publishing the Snapai project.

```bash
pnpm run build        # TypeScript compilation
pnpm run bundle       # Webpack bundling for distribution
pnpm test             # Run test suite
git tag v0.9.0        # Tag release
git push --tags       # Push to GitHub
npm publish           # Publish to npm
```

--------------------------------

### validateApiKey()

Source: https://github.com/betomoedano/snapai/blob/main/_autodocs/api-reference-validation-service.md

Validates the format of an OpenAI API key, ensuring it is not empty and starts with 'sk-'.

```APIDOC
## validateApiKey()

### Description
Validates the format of an OpenAI API key. It checks if the key is provided and if it starts with the expected prefix 'sk-'.

### Method Signature
```typescript
static validateApiKey(apiKey: string): string | null
```

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **apiKey** (`string`) - Required - API key to validate

### Returns
- `null` - if validation passed (key starts with `sk-`).
- `string` - an error message if validation failed.

### Validation Rules
- **Not empty**: API key cannot be empty.
- **Starts with `sk-`**: API key must start with 'sk-'.

### Example
```typescript
ValidationService.validateApiKey("sk-proj-xyz...");
// null (valid)

ValidationService.validateApiKey("invalid-key");
// "Invalid OpenAI API key format"

ValidationService.validateApiKey("");
// "Invalid OpenAI API key format"
```
```

--------------------------------

### Verify Keys in CI/CD

Source: https://github.com/betomoedano/snapai/blob/main/_autodocs/api-reference-config-command.md

Demonstrates how to set API keys using environment variables for CI/CD pipelines and then verify the configuration. The `snapai config --show` command will report 'Not configured' if keys are only present in environment variables, as it only displays persisted keys.

```bash
export SNAPAI_API_KEY="sk-..."
export SNAPAI_GOOGLE_API_KEY="AIzaSy..."
snapai config --show  # Displays: "Not configured" (keys come from env vars)
```

--------------------------------

### Get Style Description

Source: https://github.com/betomoedano/snapai/blob/main/_autodocs/api-reference-prompt-builders.md

Obtain a concise, human-readable description for a given style using `getStyleDescription`. This is helpful for marketing or user-facing documentation.

```typescript
StyleTemplates.getStyleDescription("minimalism");
// "Extreme reduction for clarity and function (Swiss/Braun/Apple)..."
```

--------------------------------

### ConfigCommand run() Method

Source: https://github.com/betomoedano/snapai/blob/main/_autodocs/api-reference-config-command.md

The main entry point for the config command. Parses flags and executes the appropriate configuration operation. Throws an error if API key validation fails.

```typescript
public async run(): Promise<void>
```

--------------------------------

### Get Style Directive

Source: https://github.com/betomoedano/snapai/blob/main/_autodocs/api-reference-prompt-builders.md

Generate a short, inline directive for a specific style using `getStyleDirective`. This can be appended to prompts to reinforce the desired aesthetic.

```typescript
StyleTemplates.getStyleDirective("neon");
// "Style system: NEON. Cultural DNA: Cyberpunk, Nightlife, Gaming..."
```

--------------------------------

### Configure Google API Key Locally

Source: https://github.com/betomoedano/snapai/blob/main/README.md

Stores your Google API key in the local Snapai configuration file. Use this for local development.

```bash
snapai config --google-api-key "your-google-ai-studio-key"
```

--------------------------------

### Configure API Keys

Source: https://github.com/betomoedano/snapai/blob/main/_autodocs/INDEX.md

Set your OpenAI and Google API keys for local development. Refer to configuration.md for more details.

```bash
# Local development
snapai config --openai-api-key sk-...
snapai config --google-api-key AIzaSy...
# See: configuration.md
```

--------------------------------

### Get Single Configuration Key

Source: https://github.com/betomoedano/snapai/blob/main/_autodocs/api-reference-config-service.md

Retrieves the value of a specific configuration key. Ensures type safety by accepting only valid keys from the ConfigData interface.

```typescript
static async get<K extends keyof ConfigData>(key: K): Promise<ConfigData[K]>

Reads a single configuration key from disk.

| Parameter |
|-----------|
| `key` | `K extends keyof ConfigData`
| Configuration key: `"openai_api_key"`, `"google_api_key"`, or `"default_output_path"` |

**Returns:** `Promise<ConfigData[K]>` — value of the key (or `undefined` if not set)

**Type safety:** Generic parameter ensures only valid config keys are accepted

**Example:**
```typescript
const apiKey = await ConfigService.get("openai_api_key");
// apiKey is string | undefined
```
```

--------------------------------

### Show Local Configuration

Source: https://github.com/betomoedano/snapai/blob/main/README.md

Displays the current Snapai configuration, including stored API keys.

```bash
snapai config --show
```

--------------------------------

### Run SnapAI in Watch Mode

Source: https://github.com/betomoedano/snapai/blob/main/DEV_SETUP.md

Start the TypeScript compiler in watch mode for automatic recompilation on file changes. Alternatively, use the `snapai-watch` alias.

```bash
# Terminal 1: Start TypeScript compiler in watch mode
snapai-watch
# Or manually: pnpm run dev
```

--------------------------------

### Bump beta version

Source: https://github.com/betomoedano/snapai/blob/main/PUBLISHING_GUIDE.md

Create a pre-release version tag for testing purposes.

```bash
# From a stable version (e.g. 1.1.0 -> 1.2.0-beta.0)
npm version preminor --preid beta

# For subsequent beta iterations (e.g. 1.2.0-beta.0 -> 1.2.0-beta.1)
npm version prerelease --preid beta
```

--------------------------------

### Local testing

Source: https://github.com/betomoedano/snapai/blob/main/PUBLISHING_GUIDE.md

Verify the build and package contents locally before publishing.

```bash
# Build and test
pnpm run build
./bin/dev.js --help
./bin/dev.js config --show

# Full production build
pnpm run prepare-publish
node bundle/snapai.js --help

# Preview package contents
npm pack --dry-run
```

--------------------------------

### Verify beta release

Source: https://github.com/betomoedano/snapai/blob/main/PUBLISHING_GUIDE.md

Check the beta version tags and test the beta package.

```bash
# Check the beta version
npm view snapai dist-tags

# Test it (users must explicitly opt in to beta)
npx snapai@beta --help
```

--------------------------------

### Clean and Build SnapAI Project

Source: https://github.com/betomoedano/snapai/blob/main/DEV_SETUP.md

Perform a full build of the SnapAI project, including cleaning previous builds, compiling TypeScript, and bundling with Webpack. `prepare-publish` runs the complete pipeline.

```bash
# Clean previous builds
pnpm run clean

# Full build process
pnpm run build          # TypeScript compilation
pnpm run bundle         # Webpack bundling
pnpm run prepare-publish # Complete build pipeline
```

--------------------------------

### Get Available Styles

Source: https://github.com/betomoedano/snapai/blob/main/_autodocs/api-reference-prompt-builders.md

Retrieve a list of all available style preset IDs using `getAvailableStyles`. This is useful for displaying options to the user or for programmatic style selection.

```typescript
const styles = StyleTemplates.getAvailableStyles();
// ["minimalism", "glassy", "woven", ...]
```

--------------------------------

### Invalid OpenAI API Key Format Error

Source: https://github.com/betomoedano/snapai/blob/main/_autodocs/configuration.md

This error occurs when the provided OpenAI API key does not conform to the expected format (must start with 'sk-').

```text
Error: Invalid OpenAI API key format
```

--------------------------------

### Local Development for SnapAI

Source: https://github.com/betomoedano/snapai/blob/main/_autodocs/README.md

Use 'pnpm run dev' for TypeScript compilation in watch mode. Execute the CLI from the local build using './bin/dev.js icon --prompt "calculator app"'.

```bash
# Watch mode (TypeScript compilation)
pnpm run dev

# Run CLI from local build
./bin/dev.js icon --prompt "calculator app"
```

--------------------------------

### Generate Icon with Style Hint

Source: https://github.com/betomoedano/snapai/blob/main/README.md

Generates an app icon and applies a style hint, which is appended after the initial enhancement.

```bash
# Style hint (appended after enhancement)
npx snapai icon --prompt "calculator app" --style minimalism
```

--------------------------------

### Apply Preset Styles

Source: https://github.com/betomoedano/snapai/blob/main/_autodocs/INDEX.md

Use predefined styles for icon generation. There are 16 available presets.

```bash
# Preset style (16 available)
snapai icon --prompt "..." --style minimalism
snapai icon --prompt "..." --style neon
snapai icon --prompt "..." --style kawaii
```

--------------------------------

### Gemini Banana Pro Configuration

Source: https://github.com/betomoedano/snapai/blob/main/_autodocs/configuration.md

Generate multiple images with selectable quality tiers (1k, 2k, 4k) using Gemini Banana Pro. Enable with the --pro flag.

```bash
snapai icon --prompt "app icon" --model banana --pro -n 3 --quality 2k
```

--------------------------------

### Get Gemini Client

Source: https://github.com/betomoedano/snapai/blob/main/_autodocs/api-reference-gemini-service.md

Retrieves or initializes a Google Generative AI client instance. Supports runtime API key overrides and falls back to environment variables or configuration files.

```typescript
private static async getClient(apiKeyOverride?: string): Promise<GoogleGenAI>
```

```typescript
const client = await GeminiService.getClient();
// or with override:
const client = await GeminiService.getClient("AIzaSy...");
```

--------------------------------

### Validate OpenAI API Key

Source: https://github.com/betomoedano/snapai/blob/main/_autodocs/api-reference-validation-service.md

Validates the format of an OpenAI API key. It must not be empty and must start with 'sk-'. Returns null if valid, or an error message string if invalid.

```typescript
ValidationService.validateApiKey("sk-proj-xyz...");
// null (valid)

ValidationService.validateApiKey("invalid-key");
// "Invalid OpenAI API key format"

ValidationService.validateApiKey("");
// "Invalid OpenAI API key format"
```

--------------------------------

### Troubleshooting common issues

Source: https://github.com/betomoedano/snapai/blob/main/PUBLISHING_GUIDE.md

Commands for handling version conflicts and verifying package integrity.

```bash
# Version already exists on npm
npm version patch   # Bump again and re-publish

# Test before publishing
npm pack --dry-run

# Check workflow logs
# Go to https://github.com/betomoedano/snapai/actions
```

--------------------------------

### Commit and push changes

Source: https://github.com/betomoedano/snapai/blob/main/PUBLISHING_GUIDE.md

Prepare the repository for a new version by committing and pushing local changes.

```bash
git add .
git commit -m "feat: add new feature"
git push
```

--------------------------------

### Load .env Variables and Run Snapai

Source: https://github.com/betomoedano/snapai/blob/main/_autodocs/configuration.md

Load variables from a `.env` file into the current shell session using `set -a` and `source`, then run Snapai commands.

```bash
set -a; source .env; set +a
snapai icon --prompt "calculator app"
```

--------------------------------

### ConfigCommand Constructor

Source: https://github.com/betomoedano/snapai/blob/main/_autodocs/api-reference-config-command.md

Initializes the ConfigCommand. Initialization is handled by the oclif framework.

```typescript
constructor(argv: string[], config: IConfig)
```

--------------------------------

### Preview Prompt with Snapai

Source: https://github.com/betomoedano/snapai/blob/main/_autodocs/README.md

Use this command to see the generated prompt and configuration without making an API call. Useful for debugging and refining prompts.

```bash
snapai icon --prompt "app icon" --prompt-only
```

--------------------------------

### Apply Custom Style

Source: https://github.com/betomoedano/snapai/blob/main/_autodocs/INDEX.md

Define a custom style for icon generation using a descriptive string.

```bash
# Custom style
snapai icon --prompt "..." --style "retro 80s aesthetic"
```

--------------------------------

### Configure OpenAI API Key

Source: https://github.com/betomoedano/snapai/blob/main/DEV_SETUP.md

Set your OpenAI API key using the `snapai-dev config` command. Use `--show` to verify the key has been set.

```bash
snapai-dev config --openai-api-key sk-your-openai-key-here
snapai-dev config --show
```

--------------------------------

### Run Snapai Command with Local Config

Source: https://github.com/betomoedano/snapai/blob/main/_autodocs/configuration.md

After configuring API keys, you can run Snapai commands without specifying them directly. The configuration is read from `~/.snapai/config.json`.

```bash
snapai icon --prompt "calculator app"
```

--------------------------------

### Alternative API Key Environment Variables

Source: https://github.com/betomoedano/snapai/blob/main/README.md

Shows alternative environment variable names that Snapai also supports for API keys.

```bash
# export OPENAI_API_KEY="sk-..."
# export GEMINI_API_KEY="..."
```

--------------------------------

### Test Bundled SnapAI Version

Source: https://github.com/betomoedano/snapai/blob/main/DEV_SETUP.md

Bundle the project using Webpack and then test the bundled executable. This verifies the production build output.

```bash
pnpm run bundle
node bundle/snapai.js --help
```

--------------------------------

### Generate a Single Icon

Source: https://github.com/betomoedano/snapai/blob/main/_autodocs/INDEX.md

Create an icon from a text prompt. Options include specifying the model, enabling pro features, and setting the quality.

```bash
snapai icon --prompt "calculator app"
snapai icon --prompt "weather app" --model banana --pro --quality 2k
# See: api-reference-icon-command.md
```

--------------------------------

### Handle Transparent Backgrounds with gpt-image-2

Source: https://github.com/betomoedano/snapai/blob/main/_autodocs/README.md

The 'gpt-image-2' model does not support transparent backgrounds. Use `--background opaque` or `--background auto` to ensure a solid background.

```bash
snapai icon --prompt "..." --background opaque
```

--------------------------------

### CI/CD Integration for Icon Generation

Source: https://github.com/betomoedano/snapai/blob/main/_autodocs/INDEX.md

Integrate Snapai into your CI/CD pipeline by exporting the API key as an environment variable and specifying an output directory.

```bash
export SNAPAI_API_KEY=sk-...
npx snapai icon --prompt "app icon" --output ./assets
# See: configuration.md
```

--------------------------------

### OpenAIService.getClient()

Source: https://github.com/betomoedano/snapai/blob/main/_autodocs/api-reference-openai-service.md

Retrieves or initializes an OpenAI client instance. It supports API key overrides and falls back to environment variables or configuration files.

```APIDOC
## getClient()

### Description
Retrieves or initializes an OpenAI client instance with the provided or configured API key.

### Method
`private static async getClient(apiKeyOverride?: string): Promise<OpenAI>`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **apiKeyOverride** (`string | undefined`) - Optional runtime API key override.

### Returns
- `Promise<OpenAI>` - A configured OpenAI client instance.

### Throws
- `Error` - If the OpenAI API key is not configured.

### Example
```typescript
const client = await OpenAIService.getClient();
// or with override:
const client = await OpenAIService.getClient("sk-proj-...");
```
```

--------------------------------

### Generate Camera App Icon

Source: https://github.com/betomoedano/snapai/blob/main/README.md

Create a simple camera app icon with a lens motif. This command utilizes the 'banana' model.

```bash
npx snapai icon --prompt "camera app, lens icon, simple concentric circles" --model banana
```

--------------------------------

### Snapai Module Graph

Source: https://github.com/betomoedano/snapai/blob/main/_autodocs/README.md

Illustrates the directory structure and primary files within the Snapai project, showing the organization of CLI commands, services, and utility modules.

```tree
src/
├── index.ts (oclif entry point)
├── types.ts (shared types)
├── commands/
│   ├── icon.ts (main CLI: `snapai icon`)
│   └── config.ts (configuration: `snapai config`)
├── services/
│   ├── openai.ts (OpenAI image generation)
│   ├── gemini.ts (Google Gemini image generation)
│   └── config.ts (persistent configuration)
└── utils/
    ├── icon-prompt.ts (prompt builder: buildFinalIconPrompt)
    ├── styleTemplates.ts (style system: 16 presets)
    ├── validation.ts (input validation)
    ├── branding.ts (CTA branding)
    └── prompts.ts (legacy templates)
```

--------------------------------

### Icon Command Integration with Prompt Builder

Source: https://github.com/betomoedano/snapai/blob/main/_autodocs/api-reference-prompt-builders.md

Shows how the IconCommand integrates with the `buildFinalIconPrompt` function to generate prompts for various AI services like OpenAI and Gemini.

```typescript
const finalPrompt = buildFinalIconPrompt({
  prompt: flags.prompt,
  rawPrompt: flags["raw-prompt"],
  style: flags.style,
  useIconWords: flags["use-icon-words"],
});

// Send to OpenAI or Gemini
await OpenAIService.generateIcon({ prompt: finalPrompt, ... });
// or
await GeminiService.generateBananaImages({ prompt: finalPrompt, ... });
```

--------------------------------

### Set Google API Key

Source: https://github.com/betomoedano/snapai/blob/main/_autodocs/api-reference-config-command.md

Persists the Google API key to the Snapai configuration file.

```bash
snapai config --google-api-key AIzaSy...
```

--------------------------------

### Display Current Configuration

Source: https://github.com/betomoedano/snapai/blob/main/_autodocs/api-reference-config-command.md

Shows the currently persisted configuration, including any set API keys. If no keys are set, it may display 'Not configured'.

```bash
snapai config --show
```

```bash
snapai config
```

--------------------------------

### Generate an Icon with SnapAI

Source: https://github.com/betomoedano/snapai/blob/main/README.md

Use the snapai icon command to generate an icon based on a text prompt. The output defaults to the ./assets directory with timestamped filenames.

```bash
npx snapai icon --prompt "minimalist weather app with sun and cloud"
```

--------------------------------

### Set Environment Variables for Snapai

Source: https://github.com/betomoedano/snapai/blob/main/_autodocs/configuration.md

Configure Snapai by setting environment variables. This method is recommended for CI/CD environments as it avoids persistent local configuration files.

```bash
export SNAPAI_API_KEY="sk-proj-xyz..."
export SNAPAI_GOOGLE_API_KEY="AIzaSy..."
```

--------------------------------

### Configure Google API Key

Source: https://github.com/betomoedano/snapai/blob/main/_autodocs/configuration.md

Use this command to set your Google API key persistently. This is recommended for development environments.

```bash
snapai config --google-api-key YOUR_KEY
```

--------------------------------

### Generate Icon with Transparent Background and PNG Format (GPT-1.5/GPT-1)

Source: https://github.com/betomoedano/snapai/blob/main/README.md

Generates an app icon with a transparent background and specifies the output format as PNG. This functionality is supported by GPT-1.5 and GPT-1 models, but not GPT-Image-2.

```bash
# Transparent background + output format (gpt-1.5 / gpt-1 only — not gpt-image-2)
npx snapai icon --prompt "logo mark" --model gpt-1.5 --background transparent --output-format png
```

--------------------------------

### Show Current Configuration

Source: https://github.com/betomoedano/snapai/blob/main/_autodocs/api-reference-config-command.md

Fetches and displays the current configuration, including the status of OpenAI and Google API keys (masked for security) and the default output path. Full API keys are never displayed.

```typescript
private async showConfig(): Promise<void>
```

```text
📋 Current Configuration:

🔑 OpenAI API Key: sk-...abc1
🟦 Google API Key: Not configured
   Set with: snapai config --google-api-key YOUR_KEY

Powered by Code with Beto — Learn React Native
```

--------------------------------

### Generate Icon with Specified Output Directory

Source: https://github.com/betomoedano/snapai/blob/main/README.md

Generates an app icon and saves it to a specified output directory.

```bash
# Output directory
npx snapai icon --prompt "professional banking app with secure lock" --output ./assets/icons
```

--------------------------------

### Testing and Linting Commands

Source: https://github.com/betomoedano/snapai/blob/main/CONTRIBUTING.md

Commands to ensure code quality and verify build integrity.

```bash
# Run linting
pnpm run lint

# Build to check for errors
pnpm run build

# Test CLI functionality
./bin/dev.js --help
```

--------------------------------

### Configure Snapai Locally

Source: https://github.com/betomoedano/snapai/blob/main/_autodocs/README.md

Set the OpenAI API key locally for development purposes. This allows subsequent commands to use the specified key.

```bash
snapai config --openai-api-key sk-proj-...
```

```bash
snapai icon --prompt "app icon"
```

--------------------------------

### Generate Test Icon with SnapAI

Source: https://github.com/betomoedano/snapai/blob/main/DEV_SETUP.md

Use the `snapai-dev icon` command to generate an icon based on a prompt. Specify an output directory for the generated icon.

```bash
snapai-dev icon --prompt "simple calculator app icon" --output ./test-output
```

--------------------------------

### Generate Notes App Icon

Source: https://github.com/betomoedano/snapai/blob/main/README.md

Create a minimalist and friendly notes app icon featuring a pen and paper. This uses the gpt-1 model.

```bash
npx snapai icon --prompt "notes app, pen + paper, minimal, friendly" --model gpt-1
```

--------------------------------

### getConfig

Source: https://github.com/betomoedano/snapai/blob/main/_autodocs/api-reference-config-service.md

Reads the entire configuration file from disk. Creates an empty config file if it does not exist. Errors during file reading or parsing are caught and handled gracefully, returning an empty configuration object.

```APIDOC
## getConfig

### Description
Reads the entire configuration file from disk. Creates an empty config file if it does not exist. Errors during file reading or parsing are caught and handled gracefully, returning an empty configuration object.

### Method
`static async`

### Returns
`Promise<ConfigData>` — parsed configuration object

### Example
```typescript
const config = await ConfigService.getConfig();
console.log(config.openai_api_key);
```
```

--------------------------------

### Configure OpenAI API Key Locally

Source: https://github.com/betomoedano/snapai/blob/main/_autodocs/README.md

Set your OpenAI API key for local use. This command stores the key in the Snapai configuration file.

```bash
snapai config --openai-api-key sk-...
```

--------------------------------

### Configure Snapai with Runtime Flags

Source: https://github.com/betomoedano/snapai/blob/main/_autodocs/README.md

Specify the OpenAI API key directly as a runtime flag for one-off commands. This is useful for temporary or ad-hoc usage.

```bash
snapai icon --prompt "app icon" --openai-api-key sk-proj-...
```