Skip to content

12.Headless Mode.md

Latest commit

 

History

History
541 lines (372 loc) · 14.4 KB

12.Headless Mode.md

File metadata and controls

541 lines (372 loc) · 14.4 KB

Snow CLI Usage Documentation - Headless Mode

Welcome to Snow CLI! Agentic coding in your terminal.

What is Headless Mode

Headless Mode is Snow CLI's quick conversation feature that allows you to ask questions directly from the command line and get AI responses without entering the interactive interface. It's perfect for:

  • Script automation
  • CI/CD integration
  • Quick consultations
  • Third-party tool integration

Basic Usage

Single Question

snow --ask "your question"

Examples:

snow --ask "Explain what this code does"
snow --ask "How to optimize this SQL query"
snow --ask "Explain React's useState hook"

Continuous Conversation

Headless mode supports session context persistence, allowing continuous conversations:

# First question
snow --ask "Help me create a React component"

# Output includes: SESSION_ID=abc-123-def-456

# Continue conversation using the returned Session ID
snow --ask "Add styles to this component" abc-123-def-456

# Continue further
snow --ask "Add some interactive features" abc-123-def-456

Features

Automatic Session Management

  • Each conversation automatically creates and saves a session
  • Session ID is displayed at the end of output in SESSION_ID=<uuid> format
  • Historical messages are loaded and passed to AI as context
  • Supports cross-platform session sharing (same project)

YOLO Mode

Headless mode enables YOLO mode by default (auto-approve tool calls):

  • Non-sensitive commands execute automatically
  • Sensitive commands still require manual confirmation
  • Improves automation efficiency

For sensitive command configuration, see: Sensitive Commands Configuration

File References

Headless mode supports file references in questions:

snow --ask "Analyze issues in this file @src/App.tsx"
snow --ask "Optimize this code @utils/helper.js"

Colored Output

Headless mode provides friendly colored terminal output:

  • User query: Cyan border
  • AI response: Markdown rendering with code highlighting
  • Tool execution: Yellow/Green/Red status indicators
  • Session info: Blue information box

Session Recovery Mechanism

How It Works

  1. First Conversation: Creates new session, generates UUID
  2. Save History: All messages auto-saved to ~/.snow/sessions/
  3. Provide Session ID: Displays SESSION_ID=<uuid> at end of output
  4. Restore Conversation: Loads historical messages using session ID
  5. Continue Conversation: New messages append to history

Session Format

Session information in output includes two parts:

  1. Human-Friendly Format (colored box):

    ┌─ Session Information
│  Session ID: abc-123-def-456
│  To continue this conversation, use:
│  snow --ask "your next question" abc-123-def-456
└─

  2. Machine-Parseable Format (plain text):

    SESSION_ID=abc-123-def-456

Session Storage Location

  • Windows: %USERPROFILE%\.snow\sessions\<project-name>\<date>\<UUID>.json
  • macOS/Linux: ~/.snow/sessions/<project-name>/<date>/<UUID>.json

Sessions are automatically categorized by project and date for easy management.

Third-Party Integration

Shell Script Integration

#!/bin/bash

# Execute conversation and extract Session ID
output=$(snow --ask "Create an API endpoint")
session_id=$(echo "$output" | grep "SESSION_ID=" | cut -d'=' -f2)

# Continue conversation using Session ID
snow --ask "Add error handling" "$session_id"
snow --ask "Add unit tests" "$session_id"

Python Integration

import subprocess
import re

# Execute conversation
result = subprocess.run(
    ['snow', '--ask', 'Help me analyze this error'],
    capture_output=True,
    text=True
)

# Extract Session ID
match = re.search(r'SESSION_ID=(.+)', result.stdout)
if match:
    session_id = match.group(1).strip()
    
    # Continue conversation
    subprocess.run([
        'snow', '--ask', 'How to fix this issue', session_id
    ])

Node.js Integration

const { execSync } = require('child_process');

// Execute conversation
const output = execSync('snow --ask "Create an Express route"', {
  encoding: 'utf-8'
});

// Extract Session ID
const match = output.match(/SESSION_ID=(.+)/);
if (match) {
  const sessionId = match[1].trim();
  
  // Continue conversation
  execSync(`snow --ask "Add middleware" ${sessionId}`);
}

CI/CD Integration

Using in GitHub Actions:

name: AI Code Review

on: [pull_request]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      
      - name: Setup Snow CLI
        run: npm install -g snow-ai
      
      - name: AI Review
        run: |
          # Analyze changed files
          changed_files=$(git diff --name-only HEAD^)
          
          # Request AI analysis
          output=$(snow --ask "Analyze changes in these files: $changed_files")
          
          # Extract suggestions
          echo "$output" >> $GITHUB_STEP_SUMMARY

Output Format

Standard Output Structure

╭─────────────────────────────────────────────────────────╮
│                ❆ Snow AI CLI - Headless Mode ❆          │
╰─────────────────────────────────────────────────────────╯

┌─ Continuing Session  (if continuing conversation)
│  Session ID: abc-123-def-456
│  Previous messages: 4

┌─ User Query
│  Your question content

└─ Assistant Response

AI response content (Markdown format with code highlighting)

┌─ Session Information
│  Session ID: abc-123-def-456
│  To continue this conversation, use:
│  snow --ask "your next question" abc-123-def-456
└─

SESSION_ID=abc-123-def-456

Parsing Recommendations

For script and tool integration, recommended parsing methods:

  1. Extract Session ID:

    • Use regex /SESSION_ID=(.+)/
    • Or simply find last line with SESSION_ID= prefix

  2. Extract AI Response:

    • Find content after └─ Assistant Response
    • Remove ANSI color codes (if needed)

  3. Error Handling:

    • Check exit code
    • Look for ✗ Error: marker

Use Cases

Code Review Assistant

# Quick code review
git diff | snow --ask "Review these code changes and point out potential issues"

# Targeted review
snow --ask "Does this code have performance issues @src/utils/parser.ts"

Documentation Generation

# Generate function documentation
snow --ask "Generate JSDoc comments for this function @src/api.ts"

# Generate README
snow --ask "Generate project README based on code structure @src/"

Quick Consultation

# Technical questions
snow --ask "How to use React 18's concurrent features"

# Debugging suggestions
snow --ask "How to solve this error: TypeError: Cannot read property 'map' of undefined"

Automated Workflows

#!/bin/bash

# Automated code optimization workflow
output=$(snow --ask "Analyze project dependencies @package.json")
session_id=$(echo "$output" | grep "SESSION_ID=" | cut -d'=' -f2)

snow --ask "Suggest dependencies that need updating" "$session_id"
snow --ask "Generate dependency update script" "$session_id"

Test Generation

# Generate unit tests
snow --ask "Generate unit tests for this function @src/calculator.ts"

# Generate test data
output=$(snow --ask "Generate test user data in JSON format")
session_id=$(echo "$output" | grep "SESSION_ID=" | cut -d'=' -f2)

snow --ask "Generate 10 more variant data" "$session_id"

Best Practices

1. Clear Question Descriptions

# Good example
snow --ask "Optimize this SQL query's performance, focus on index usage @query.sql"

# Not clear enough
snow --ask "Optimize @query.sql"

2. Reasonable Use of Session Context

# Continuous conversation after establishing context
output=$(snow --ask "Create a user authentication system")
session_id=$(echo "$output" | grep "SESSION_ID=" | cut -d'=' -f2)

# Subsequent questions can be more concise
snow --ask "Add password reset feature" "$session_id"
snow --ask "Add email verification" "$session_id"

3. Handling Long-Running Tasks

For tasks that may require extended thinking:

# Complex tasks may need more time
snow --ask "Refactor entire authentication module using best practices @src/auth/"

Wait for AI to complete thinking and tool calls.

4. Combine with Command Injection

# Embed real-time information in question
snow --ask "Analyze current Git branch status !`git status` and provide suggestions"

For command injection, see: Command Injection Mode

5. Error Handling

#!/bin/bash

# Error handling in scripts
if ! output=$(snow --ask "your question" 2>&1); then
    echo "Error: AI conversation failed"
    echo "$output"
    exit 1
fi

# Check if Session ID was successfully generated
if ! echo "$output" | grep -q "SESSION_ID="; then
    echo "Warning: Failed to retrieve Session ID"
fi

Limitations and Considerations

Unsupported Features

  1. Interactive Tools:

    • askuser tool is not available
    • Cannot request user input in headless mode

  2. Plan Mode:

    • Headless mode doesn't support Plan mode
    • All tool calls execute immediately (YOLO mode)

  3. Real-time Update Display:

    • No real-time streaming output to terminal
    • Results displayed all at once after completion

Security Considerations

  1. Sensitive Command Confirmation:

    • Even in YOLO mode, sensitive commands still require confirmation
    • Not suitable for fully unattended automation

  2. API Key Protection:

    • When using in CI/CD, ensure API keys are securely stored
    • Use environment variables or secret management services

  3. Output Content Review:

    • AI output may contain sensitive information
    • Be careful to filter when using in public logs

Performance Considerations

  1. Session Size:

    • Long session history increases token consumption
    • Recommend periodically starting new sessions

  2. Concurrency Limits:

    • Be aware of API rate limiting when running multiple headless mode instances

  3. Network Latency:

    • Response time depends on network and AI service
    • Consider setting reasonable timeouts

FAQ

Q: What's the difference between headless mode and interactive mode?

A: Headless mode is single-execution mode that automatically exits after completion, suitable for scripts and automation. Interactive mode provides a complete UI interface with persistent conversations and more advanced features.

Q: Does Session ID expire?

A: Session IDs don't expire; session files are permanently saved locally. However, very old sessions may affect performance due to large context size.

Q: Can sessions be shared across different projects?

A: No. Sessions are categorized and stored by project path, ensuring conversations from different projects don't get mixed.

Q: How to view all historical sessions?

A: Sessions are saved in ~/.snow/sessions/ directory, organized by project and date. You can browse using file manager, or use snow --task-list to view task sessions.

Q: What if Session ID is lost?

A: You can find the most recent session file in the session storage directory; the filename is the Session ID. Or use interactive mode's /history command to view historical sessions.

Q: Does headless mode support file uploads?

A: Supports file references via @filepath syntax, but doesn't support image uploads. For image analysis, use interactive mode.

Q: How to use different API configurations in headless mode?

A: Headless mode uses global configuration file (~/.snow/profiles.json). To switch configurations, first switch Profile in interactive mode, or edit the configuration file directly.

Q: How to remove ANSI color codes from output?

A:

# Use sed to remove color codes
snow --ask "your question" | sed 's/\x1b\[[0-9;]*m//g'

# Or use other tools
snow --ask "your question" | ansi2txt

Q: Can output be redirected to file?

A: Yes, but will preserve ANSI color codes:

snow --ask "your question" > output.txt

# Save to file and display in terminal
snow --ask "your question" | tee output.txt

Configuration File Locations

Headless mode uses global configurations:

  • API Configuration: ~/.snow/profiles.json
  • Sensitive Commands: ~/.snow/sensitive-commands.json
  • Session Storage: ~/.snow/sessions/<project-name>/<date>/

For configuration methods, see: First Time Configuration

Related Features

Example Scripts

Complete Automation Example

#!/bin/bash

# Color definitions
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
NC='\033[0m' # No Color

# Error handling
set -e
trap 'echo -e "${RED}Script execution failed${NC}"' ERR

echo -e "${YELLOW}Starting automated code review...${NC}"

# Get changed files
changed_files=$(git diff --name-only HEAD^ | tr '\n' ' ')

if [ -z "$changed_files" ]; then
    echo -e "${RED}No file changes detected${NC}"
    exit 0
fi

echo -e "${GREEN}Detected changed files: $changed_files${NC}"

# Initial review
echo -e "${YELLOW}Performing initial code review...${NC}"
output=$(snow --ask "Review changes in these files: $changed_files")

# Extract Session ID
session_id=$(echo "$output" | grep "SESSION_ID=" | cut -d'=' -f2)

if [ -z "$session_id" ]; then
    echo -e "${RED}Unable to retrieve Session ID${NC}"
    exit 1
fi

echo -e "${GREEN}Session ID: $session_id${NC}"

# Detailed analysis
echo -e "${YELLOW}Requesting security analysis...${NC}"
snow --ask "Analyze these changes from security perspective" "$session_id"

echo -e "${YELLOW}Requesting performance analysis...${NC}"
snow --ask "Analyze these changes from performance perspective" "$session_id"

echo -e "${GREEN}Code review completed!${NC}"

This script demonstrates how to:

  • Error handling and colored output
  • Session ID extraction and validation
  • Multiple rounds of continuous conversation
  • Automated workflow integration