Skip to content

02.First Time Configuration.md

Latest commit

 

History

History
552 lines (336 loc) · 15.4 KB

02.First Time Configuration.md

File metadata and controls

552 lines (336 loc) · 15.4 KB

Snow CLI User Documentation - First Time Configuration

Welcome to Snow CLI! Agentic coding in your terminal.

First Time Configuration

1. Launch from Any Directory

  1. Type snow to start Snow CLI or click the launch icon in the IDE plugin

  2. Snow CLI's default language is English. You can go to Language Settings to modify your language preference

    alt text

2. Enter Configuration Interface

After setting your language preference, go to API and Model Settings

alt text

The configuration interface provides comprehensive AI service configuration capabilities, supporting multiple profile management and rich model parameter settings.

Detailed Configuration Options

Profile Management

Purpose: Manage multiple configuration sets for quick switching between different scenarios

Operations:

  • Press Enter to access the profile selection interface
  • Use up/down arrow keys to select profiles
  • The currently active profile will display a green ✓ mark

Quick Actions:

  • Press n key: Create new profile (requires entering profile name)
  • Press d key: Delete current profile (the default profile cannot be deleted)

Important Notes:

  • Each profile independently saves all settings
  • Switching profiles immediately loads all settings from that profile

Basic Configuration

Base URL (Required)

Purpose: Base address of the API service

Configuration Method:

  • Press Enter to enter edit mode
  • Input the complete API address
  • Press Enter again to confirm

Standard Addresses:

alt text

  1. OpenAI Chat Completion

    https://api.openai.com/v1

    For OpenAI's standard chat completion API

  2. OpenAI Responses

    https://api.openai.com/v1

    For OpenAI's response API with reasoning capabilities

  3. Gemini

    https://generativelanguage.googleapis.com/v1beta

    Google Gemini API service address

  4. Anthropic

    https://api.anthropic.com/v1

    API service address for Claude models

Important Notes:

  • Supports proxy or third-party relay service addresses
  • Ensure the address format is correct, starting with https://
  • Address typically includes version number at the end (e.g., /v1)

API Key (Required)

Purpose: Access key for API service

Configuration Method:

  • Press Enter to enter edit mode
  • Input the complete API Key
  • Input will be automatically hidden and displayed as * characters
  • Press Enter again to confirm

Important Notes:

  • API Keys typically start with specific prefixes (e.g., sk- for OpenAI)
  • Keep your API Key secure to prevent disclosure
  • Will only display as asterisks, never in plain text

Request Method

Purpose: Select API calling method; different methods support different features

Available Options:

  • OpenAI Chat Completion: Standard OpenAI chat API
  • OpenAI Responses: OpenAI API with reasoning mode support
  • Gemini: Google's Gemini model
  • Anthropic: Claude model

Configuration Method:

  • Press Enter to open selection list
  • Use up/down arrow keys to select
  • Press Enter to confirm

Important Notes:

  • Different request methods display different advanced configuration options
  • When switching request methods, specific feature configurations will automatically adjust

System Prompt (Optional)

Purpose: Select which system prompt to use for the current profile

Available Options:

  • Follow Global (None): Use global settings, no system prompt currently activated
  • Follow Global (Name): Use the system prompt activated in global settings
  • Not Use: Explicitly disable system prompt, even if there's an activated global prompt
  • Select Specific Prompt: Choose from the list of configured system prompts

Configuration Method:

  • Press Enter to open selection list
  • Use up/down arrow keys to select
  • Press Enter to confirm

Description:

  • System prompts can be created and managed in the "System Prompt Management" interface
  • Profile-level settings override global settings
  • Selecting "Not Use" allows you to temporarily disable system prompts in specific scenarios

Custom Headers (Optional)

Purpose: Select which custom headers scheme to use for the current profile

Available Options:

  • Follow Global (None): Use global settings, no headers scheme currently activated
  • Follow Global (Name): Use the headers scheme activated in global settings
  • Not Use: Explicitly disable custom headers, even if there's an activated global scheme
  • Select Specific Scheme: Choose from the list of configured headers schemes

Configuration Method:

  • Press Enter to open selection list
  • Use up/down arrow keys to select
  • Press Enter to confirm

Description:

  • Custom headers schemes can be created and managed in the "Custom Headers Management" interface
  • Profile-level settings override global settings
  • Selecting "Not Use" allows you to temporarily disable custom headers in specific scenarios

Advanced Configuration

Enable Auto Compress

Purpose: Automatically compress long text content to reduce token consumption

Default: Enabled

Configuration Method:

  • Press Enter or Space key to toggle Enabled/Disabled status
  • Displays "Enabled" or "Disabled"

Recommendation: Enabling can reduce API call costs but may lose some context details

Show Thinking

Purpose: Display AI's reasoning and thinking process in the interface

Default: Enabled

Configuration Method:

  • Press Enter or Space key to toggle Enabled/Disabled status
  • Displays "Enabled" or "Disabled"

Recommendation: Enabling helps understand AI's reasoning process, useful for debugging and understanding results

Anthropic-Specific Configuration

When selecting the Anthropic request method, the following configuration options will appear:

Anthropic Beta

Purpose: Enable Anthropic's Beta version features

Default: Disabled

Configuration Method:

  • Press Enter or Space key to toggle Enabled/Disabled status

Important Notes: Beta features may be unstable, use with caution

Anthropic Cache TTL

Purpose: Set the expiration time for prompt caching

Available Options:

  • 5m: 5 minutes
  • 1h: 1 hour

Default: 5 minutes

Configuration Method:

  • Press Enter to open selection list
  • Select cache duration
  • Press Enter to confirm

Description: Longer cache times can reduce token consumption for repeated content

Thinking Enabled

Purpose: Enable Claude's extended thinking feature

Default: Disabled

Configuration Method:

  • Press Enter or Space key to toggle Enabled/Disabled status

Description: When enabled, AI will perform deeper reasoning

Thinking Budget Tokens

Purpose: Set the maximum token count for extended thinking mode

Default: 10000

Range: Minimum value 1000

Configuration Method:

  • Press Enter to enter edit mode
  • Input number (supports backspace deletion)
  • Press Enter to confirm

Important Notes:

  • Larger thinking budget enables deeper AI reasoning but consumes more tokens
  • If input value is below minimum, it will automatically adjust to minimum value when saved

Gemini-Specific Configuration

When selecting the Gemini request method, the following configuration options will appear:

Gemini Thinking Enabled

Purpose: Enable Gemini's thinking and reasoning feature

Default: Disabled

Configuration Method:

  • Press Enter or Space key to toggle Enabled/Disabled status

Gemini Thinking Budget

Purpose: Set the budget value for Gemini thinking mode

Default: 1024

Range: Minimum value 1

Configuration Method:

  • Press Enter to enter edit mode
  • Input number (supports backspace deletion)
  • Press Enter to confirm

OpenAI Responses-Specific Configuration

When selecting the OpenAI Responses request method, the following configuration options will appear:

Responses Reasoning Enabled

Purpose: Enable OpenAI's reasoning feature

Default: Disabled

Configuration Method:

  • Press Enter or Space key to toggle Enabled/Disabled status

Responses Reasoning Effort

Purpose: Set the intensity level of reasoning mode

Available Options:

  • LOW: Low-intensity reasoning
  • MEDIUM: Medium-intensity reasoning
  • HIGH: High-intensity reasoning
  • XHIGH: Ultra-high intensity reasoning (only supported in responses method)

Default: HIGH

Configuration Method:

  • Press Enter to open selection list
  • Use up/down arrow keys to select intensity
  • Press Enter to confirm

Important Notes: Higher reasoning intensity provides deeper reasoning but increases time and token consumption

Model Configuration

Advanced Model

Purpose: Primary model for complex tasks

Configuration Method:

  1. Press Enter to automatically fetch available model list (requires correct Base URL and API Key configuration)
  2. If fetching fails, will automatically enter manual input mode
  3. Can use alphanumeric input for fuzzy search filtering
  4. Select "Manual Input" option to manually enter model name
  5. Press m key to quickly enter manual input mode

Common Model Examples:

  • OpenAI: gpt-4, gpt-4-turbo, gpt-4o
  • Claude: claude-3-5-sonnet-20241022, claude-3-opus-20240229
  • Gemini: gemini-2.0-flash-exp, gemini-pro

Recommendation: Choose more powerful models for complex programming tasks

Basic Model

Purpose: Auxiliary model for simple tasks

Configuration Method: Same as Advanced Model

Common Model Examples:

  • OpenAI: gpt-3.5-turbo, gpt-4o-mini
  • Claude: claude-3-haiku-20240307
  • Gemini: gemini-flash

Recommendation: Choose models with fast response speed and lower cost

Max Context Tokens

Purpose: Maximum context window size supported by the model

Default: 4000

Range: Minimum value 4000

Configuration Method:

  • Press Enter to enter edit mode
  • Input number (supports backspace deletion)
  • Press Enter to confirm

Common Model Context Capacities:

  • Claude 3.5 Sonnet: 200000
  • GPT-4 Turbo: 128000
  • GPT-4: 8192
  • Gemini 2.0 Flash: 1000000
  • Gemini Pro: 32768

Important Notes:

  • Must be set to the actual context size supported by the model
  • Setting too high will cause API call failures
  • Setting too low will limit conversation length

Max Tokens

Purpose: Maximum token count allowed for single response generation

Default: 4096

Range: Minimum value 100

Configuration Method:

  • Press Enter to enter edit mode
  • Input number (supports backspace deletion)
  • Press Enter to confirm

Common Model Output Capacities:

  • Claude 3.5 Sonnet: 64000
  • GPT-4 Turbo: 4096
  • GPT-4: 8192
  • Gemini 2.0 Flash: 8192

Important Notes:

  • Different models support different maximum output token counts
  • Setting too high will increase response time and cost
  • Recommend setting reasonably based on actual needs

Edit Similarity Threshold (Advanced Option, Change with Caution)

Purpose: Controls matching precision when AI modifies files, affecting code editing accuracy

Default: 0.75

Range: 0.1 - 1.0 (decimal)

Configuration Method:

  • Press Enter to enter edit mode
  • Input decimal number (e.g., 0.75, 0.8)
  • Supports backspace deletion
  • Press Enter to confirm

Explanation:

  • Higher threshold: Stricter matching, only very similar code will be modified, reducing risk of incorrect modifications
  • Lower threshold: Looser matching, allows more differences (like indentation, whitespace), increasing flexibility
  • Default 0.75: Balances precision and flexibility, suitable for most scenarios

Recommendations:

  • Keep default value unless encountering specific issues
  • If AI frequently can't find code to modify, slightly decrease (e.g., 0.6-0.7)
  • If AI incorrectly modifies similar but different code, slightly increase (e.g., 0.8-0.85)
  • Not recommended to set below 0.6 or above 0.9

Important Notes:

  • This configuration affects all code editing operations
  • Changes take effect immediately without restart
  • Incorrect settings may cause code editing failures or incorrect modifications

Configuration Interface Operations

Basic Operations

  • Up/Down Arrow Keys: Move between configuration items
  • Enter Key: Enter edit mode or confirm input
  • Esc Key: Save configuration and exit
  • Ctrl+S / Cmd+S: Quick save configuration
  • Space Key: Toggle switch-type configuration items (e.g., Enable/Disable)

Navigation Tips

  • Configuration interface displays current position at top: (Current item/Total items)
  • When configuration items exceed 8, will automatically scroll
  • Currently selected configuration item displays ❯ marker

Enhanced Model Selection Features

In the model selection interface:

  • Alphanumeric Input: Real-time filtering of model list
  • Backspace: Delete filter characters
  • Esc Key: Exit selection interface
  • m Key: Quick entry to manual input mode

Enhanced Number Input

When editing token-related configurations:

  • Number Keys: Append digits
  • Backspace/Delete: Delete last digit
  • Enter Key: Confirm and automatically validate minimum value

Configuration Validation

The system will automatically validate when saving configuration:

  1. Required Field Check: Base URL and API Key must be filled
  2. Format Validation: Check if Base URL format is correct
  3. Value Range: Automatically adjust token configurations above minimum values
  4. Request Method Matching: Validate compatibility between selected model and request method

Error Messages:

  • Red error information will display at bottom of interface when validation fails
  • Can try saving again after fixing errors

Configuration File Storage

  • Main Configuration File: ~/.snowcli/config.json
  • Profile Directory: ~/.snowcli/profiles/
  • Auto Save: Automatically saves to currently active profile when exiting configuration interface

FAQ

1. Unable to fetch model list?

Solution:

  • Check if Base URL and API Key are correct
  • Check network connection and proxy settings
  • If it continues to fail, use manual input mode (press m key)

2. Configuration doesn't take effect after saving?

Solution:

  • Confirm you have saved configuration by pressing Esc or Ctrl+S
  • Restart Snow CLI to ensure configuration is loaded
  • Check if the correct profile is selected

3. Token limit exceeded error?

Solution:

  • Check if Max Context Tokens is set correctly
  • Confirm it doesn't exceed the model's actual supported context size
  • Appropriately reduce Max Tokens setting

4. Configuration lost after switching request methods?

Explanation: Specific configuration items for different request methods (such as Anthropic's Thinking feature) will automatically show/hide based on the current method. Configuration values are still saved and will be restored when switching back.

Configuration Best Practices

  1. First-Time Configuration: First set Basic configuration (Base URL, API Key, Request Method), then configure advanced features
  2. Multi-Scenario Usage: Create different profiles for different projects
  3. Cost Optimization: Reasonably set Max Tokens, enable Auto Compress feature
  4. Performance Optimization: Choose appropriate models based on task complexity, use Basic Model for simple tasks
  5. Debugging Recommendation: Enable Show Thinking to view AI reasoning process, helpful for understanding and optimizing prompts