Configuration Files

Overview

VibeKit CLI stores configuration and data in the ~/.vibekit/ directory. These files control sandbox behavior, redaction settings, analytics, and logging preferences.

File Locations

User Configuration Directory

All VibeKit CLI files are stored in ~/.vibekit/:

File	Location	Purpose
`settings.json`	`~/.vibekit/settings.json`	User preferences and feature toggles
`logs/`	`~/.vibekit/logs/`	Agent interaction logs by date
`analytics/`	`~/.vibekit/analytics/`	Usage statistics and performance data

Project Files

File	Location	Purpose
`.env`	Project root	Environment variables (API keys)

Settings Configuration

~/.vibekit/settings.json

Controls VibeKit CLI behavior and features:

{
  "sandbox": {
    "enabled": false
  },
  "redaction": {
    "enabled": true
  },
  "analytics": {
    "enabled": true
  },
  "aliases": {
    "enabled": false
  }
}

Settings Options

Sandbox Settings

Option	Type	Default	Description
`sandbox.enabled`	`boolean`	`false`	Enable Docker sandbox by default

When enabled, agents run in Docker containers instead of directly on your system.

Redaction Settings

Option	Type	Default	Description
`redaction.enabled`	`boolean`	`true`	Enable automatic PII redaction from outputs

The redaction system automatically removes sensitive information from agent outputs.

Analytics Settings

Option	Type	Default	Description
`analytics.enabled`	`boolean`	`true`	Track usage statistics and performance

Analytics track session duration, success rates, and error patterns.

Aliases Settings

Option	Type	Default	Description
`aliases.enabled`	`boolean`	`false`	Enable global command aliases

When enabled, you can use claude instead of vibekit claude.

Managing Settings

Interactive Settings

Use the interactive settings interface:

vibekit

This provides a TUI for toggling options:

Navigate with arrow keys
Toggle with space bar
Save with enter

Manual Editing

Edit settings directly:

# Open in editor
vi ~/.vibekit/settings.json

# Validate JSON
cat ~/.vibekit/settings.json | jq '.'

Environment Variables

API Keys

Set API keys for your agents:

# Claude Code CLI
export ANTHROPIC_API_KEY="sk-ant-..."

# Gemini CLI (when available)
export GOOGLE_API_KEY="..."

# Add to shell profile for persistence
echo 'export ANTHROPIC_API_KEY="sk-ant-..."' >> ~/.zshrc
source ~/.zshrc

Network Configuration

Configure network settings:

# Use external proxy if needed
export HTTP_PROXY="http://proxy.example.com:8080"
export HTTPS_PROXY="http://proxy.example.com:8080"

# Enable debug logging
export VIBEKIT_DEBUG="1"

Project-Level Environment

Create .env file in your project:

# .env
ANTHROPIC_API_KEY=sk-ant-...
GOOGLE_API_KEY=...

# Custom environment variables for your project
DATABASE_URL=postgresql://...
API_BASE_URL=https://api.example.com

Data Storage

Log Files

Logs are organized by date in ~/.vibekit/logs/:

~/.vibekit/logs/
├── 2024-01-15/
│   ├── claude-10-30-00.log
│   ├── claude-14-45-12.log
│   └── gemini-16-20-35.log
├── 2024-01-16/
│   └── claude-09-15-42.log

Each log file contains:

Agent commands and arguments
Execution output and errors
Performance timings
File changes made

Analytics Data

Analytics are stored in ~/.vibekit/analytics/:

~/.vibekit/analytics/
├── sessions/
│   ├── claude-2024-01-15.json
│   └── gemini-2024-01-15.json
└── summary.json

Data includes:

Session duration and outcome
Commands executed
Files modified
Error messages and warnings

Global Aliases

Setting Up Aliases

Enable global aliases to use claude directly:

# Enable in settings
vibekit  # Toggle aliases to enabled

# Install aliases to shell
vibekit setup-aliases

# Restart terminal or reload shell
source ~/.zshrc

Using Aliases

After setup, use commands directly:

# Instead of: vibekit claude "Generate code"
claude "Generate code"

# Instead of: vibekit gemini "Ask question"
gemini "Ask question"

Diagnosing Alias Issues

Check alias setup:

vibekit diagnose-aliases

This shows:

Settings status
VibeKit command availability
Shell alias functionality
Current active aliases

Configuration Precedence

Settings are applied in this order (later overrides earlier):

Built-in defaults
Settings file (~/.vibekit/settings.json)
Environment variables
Command line options

Example:

# Settings: sandbox.enabled = false
# Environment: (none)
# Command line wins:
vibekit claude --sandbox docker "Generate code"

Backup and Restore

Manual Backup

Create backup of all VibeKit data:

# Create timestamped backup
BACKUP_DIR="$HOME/vibekit-backup-$(date +%Y%m%d-%H%M%S)"
cp -r ~/.vibekit "$BACKUP_DIR"
tar -czf "$BACKUP_DIR.tar.gz" -C "$HOME" "$(basename "$BACKUP_DIR")"
rm -rf "$BACKUP_DIR"

echo "Backup created: $BACKUP_DIR.tar.gz"

Restore Configuration

# Restore from backup
tar -xzf ~/vibekit-backup-20240115-103000.tar.gz -C ~/
mv ~/vibekit-backup-20240115-103000 ~/.vibekit

Maintenance

Clean Data

Remove old logs and analytics:

# Clean all data
vibekit clean

# Clean specific data types
vibekit clean --logs      # Remove log files
vibekit clean --analytics # Remove analytics data
vibekit clean --docker   # Remove Docker resources

Reset Configuration

Reset settings to defaults:

# Remove settings file (will recreate with defaults)
rm ~/.vibekit/settings.json

# Or reset all data (careful!)
rm -rf ~/.vibekit

Troubleshooting

Corrupted Settings

Check settings file validity:

# Validate JSON
jq '.' ~/.vibekit/settings.json

# Fix corrupted file
echo '{}' > ~/.vibekit/settings.json

Permission Issues

Fix file permissions:

# Ensure proper ownership and permissions
chmod 700 ~/.vibekit
find ~/.vibekit -type f -exec chmod 600 {} \;

# Check current permissions
ls -la ~/.vibekit/

Missing Dependencies

Check for required tools:

# Check for Claude Code CLI
claude --version

# Check for Docker (if using sandbox)
docker --version

# Diagnose common issues
vibekit diagnose-aliases

Best Practices

1. Secure API Keys

Never commit API keys to version control:

# .gitignore
.env
*.log

Use environment variables or secure storage.

2. Regular Cleanup

Set up automatic cleanup:

# Add to crontab for weekly cleanup
0 0 * * 0 vibekit clean --logs

3. Monitor Usage

Use analytics to understand your usage patterns:

# Weekly usage review
vibekit analytics --days 7 --summary

# Export for analysis
vibekit analytics --export weekly-report.json --days 7

4. Safe Experimentation

Enable Docker sandbox for unknown or experimental prompts:

# Enable sandbox in settings for safety
vibekit

# Or use per-command
vibekit claude --sandbox docker "Experimental code generation"

Environment Variables - Runtime configuration
Installation - Initial setup
Quick Reference - Common commands

Getting Started

Core Features

Configuration

Documentation Index

​Overview

​File Locations

​User Configuration Directory

​Project Files

​Settings Configuration

​~/.vibekit/settings.json

​Settings Options

​Sandbox Settings

​Redaction Settings

​Analytics Settings

​Aliases Settings

​Managing Settings

​Interactive Settings

​Manual Editing

​Environment Variables

​API Keys

​Network Configuration

​Project-Level Environment

​Data Storage

​Log Files

​Analytics Data

​Global Aliases

​Setting Up Aliases

​Using Aliases

​Diagnosing Alias Issues

​Configuration Precedence

​Backup and Restore

​Manual Backup

​Restore Configuration

​Maintenance

​Clean Data

​Reset Configuration

​Troubleshooting

​Corrupted Settings

​Permission Issues

​Missing Dependencies

​Best Practices

​1. Secure API Keys

​2. Regular Cleanup

​3. Monitor Usage

​4. Safe Experimentation

​Related Topics