The VSKI Agent CLI supports extensive configuration through environment variables and .env files. This allows you to customize the framework's behavior without modifying code.

Quick Start

Using Environment Variables

# Set configuration directory
export VSKI_CONFIG_DIR=/path/to/config

# Set config filename
export VSKI_AGENT_CONFIG=my-config.yaml

# Run CLI
vski-agent config list

Using .env Files

Create a .env file in your project directory:

# .env
VSKI_CONFIG_DIR=/custom/config/path
VSKI_AGENT_CONFIG=production.yaml
VSKI_VERBOSE=true

The CLI automatically loads .env files from the current directory. You can also specify a custom env file:

vski-agent --env-file .env.production config list

Environment Variables

Core Configuration

`VSKI_AGENT_CONFIG`

Description: Configuration filename
Default: agent.config.yaml
Example: VSKI_AGENT_CONFIG=my-config.yaml

The name of the configuration file that the CLI searches for in configuration directories.

`VSKI_CONFIG_DIR`

Description: Base configuration directory
Default: ~/.config/vski-agent
Example: VSKI_CONFIG_DIR=/opt/vski-agent/config

The primary directory where global configuration files are stored. This is the first location searched for configuration files.

`VSKI_AGENTS_DIR`

Description: Global agents directory
Default: ~/.config/vski-agent/agents
Example: VSKI_AGENTS_DIR=/shared/agents

Directory where global agent configuration files (.md files) are stored.

Data and Storage

`VSKI_DATA_DIR`

Description: Base data directory for persistent storage
Default: ~/.local/share/vski-agent
Example: VSKI_DATA_DIR=/var/lib/vski-agent

Base directory for all persistent data storage including sessions and logs.

`VSKI_PERSISTENCE_DIR`

Description: Sessions persistence directory
Default: ~/.local/share/vski-agent/sessions
Example: VSKI_PERSISTENCE_DIR=/data/vski-agent/sessions

Directory where conversation sessions are saved.

`VSKI_LOGS_DIR`

Description: Logs directory
Default: ~/.local/share/vski-agent/logs
Example: VSKI_LOGS_DIR=/var/log/vski-agent

Directory where application logs are stored.

Local Configuration

`VSKI_LOCAL_AGENTS_DIR`

Description: Local agents directory (relative to current working directory)
Default: .agents
Example: VSKI_LOCAL_AGENTS_DIR=my-agents

Name of the agents directory in the current working directory. This is searched with higher priority than the global agents directory.

`VSKI_LOCAL_CONFIG_DIR`

Description: Local config directory
Default: . (current directory)
Example: VSKI_LOCAL_CONFIG_DIR=config

Directory where local configuration files are searched. Usually the current working directory.

Behavior and Debugging

`VSKI_DEFAULT_RULES`

Description: Default rules filename
Default: AGENTS.md
Example: VSKI_DEFAULT_RULES=rules.md

The default rules file that agents load if no specific rules are configured.

`VSKI_VERBOSE`

Description: Enable verbose output mode
Default: false
Values: true, false, 1, 0
Example: VSKI_VERBOSE=true

When enabled, provides more detailed output and error messages including stack traces.

`VSKI_DEBUG`

Description: Enable debug mode
Default: false
Values: true, false, 1, 0
Example: VSKI_DEBUG=true

Enables additional debugging features and logging.

Configuration Priority

Configuration values are loaded with the following priority (highest to lowest):

Command-line arguments (e.g., --config, --env-file)
Environment variables (set in shell or loaded from .env files)
Default values (built into the application)

Example Priority Resolution

# Default: ~/.config/vski-agent
export VSKI_CONFIG_DIR=/home/user/my-config

# But command-line override takes precedence:
vski-agent --config /opt/config config list
# Uses /opt/config (command-line wins)

.env File Format

The CLI supports standard .env file format with the following features:

Basic Format

# Comments are supported (lines starting with #)
KEY=value
ANOTHER_KEY="value with spaces"
QUOTED='single quotes also work'

Features

Comments: Lines starting with # are ignored
Blank lines: Ignored
Quoting: Both double quotes (") and single quotes (') are supported
Spaces: Spaces around = are trimmed
Override protection: Environment variables already set in the shell are not overridden

Example .env File

# VSKI Agent Configuration
# Generated: 2024-01-15

# Use production configuration
VSKI_AGENT_CONFIG=production.yaml

# Custom config directory
VSKI_CONFIG_DIR=/opt/vski-agent/config

# Shared agents library
VSKI_AGENTS_DIR=/shared/agents

# Enable verbose mode for debugging
VSKI_VERBOSE=true

# Custom data directory
VSKI_DATA_DIR=/data/vski-agent

CLI Commands

View Current Configuration

# Show all environment configuration values
vski-agent env

This displays all current configuration values and their sources.

Load Custom Environment File

# Load from specific file
vski-agent --env-file .env.production config list

# Short form
vski-agent -e .env.staging agent list

Override Config Directory

# Use custom config directory
vski-agent --config /path/to/config init

# Short form
vski-agent -c /path/to/config config list

Configuration Search Paths

The CLI searches for configuration files in multiple locations with the following priority:

For Configuration Files

Local config directory (default: current directory)
Global config directory (VSKI_CONFIG_DIR, default: ~/.config/vski-agent)

For Agent Files

Local agents directory (VSKI_LOCAL_AGENTS_DIR, default: .agents)
Global agents directory (VSKI_AGENTS_DIR, default: ~/.config/vski-agent/agents)

For Rules Files

Current working directory
Global config directory
Home directory

Usage Examples

Development Setup

# .env.development
VSKI_AGENT_CONFIG=development.yaml
VSKI_VERBOSE=true
VSKI_DEBUG=true
VSKI_LOCAL_AGENTS_DIR=dev-agents

vski-agent -e .env.development init

Production Deployment

# .env.production
VSKI_CONFIG_DIR=/etc/vski-agent
VSKI_DATA_DIR=/var/lib/vski-agent
VSKI_LOGS_DIR=/var/log/vski-agent
VSKI_PERSISTENCE_DIR=/var/lib/vski-agent/sessions
VSKI_AGENT_CONFIG=production.yaml

vski-agent -e /etc/vski-agent/.env config validate

Multi-Environment Setup

# Project structure:
# ├── .env.development
# ├── .env.staging
# ├── .env.production
# ├── development.yaml
# ├── staging.yaml
# └── production.yaml

# Switch between environments
vski-agent -e .env.development config list
vski-agent -e .env.staging config list
vski-agent -e .env.production config list

Shared Team Configuration

# .env (committed to repository)
VSKI_LOCAL_AGENTS_DIR=.agents
VSKI_DEFAULT_RULES=RULES.md
VSKI_AGENT_CONFIG=team-config.yaml

# .env.local (not committed, individual overrides)
VSKI_VERBOSE=true
VSKI_DEBUG=true

# Load both files (team defaults + local overrides)
vski-agent config list

Integration with Shell

Bash/Zsh

Add to your .bashrc or .zshrc:

# VSKI Agent configuration
export VSKI_CONFIG_DIR="$HOME/.config/vski-agent"
export VSKI_DATA_DIR="$HOME/.local/share/vski-agent"

Fish

Add to your config.fish:

# VSKI Agent configuration
set -x VSKI_CONFIG_DIR $HOME/.config/vski-agent
set -x VSKI_DATA_DIR $HOME/.local/share/vski-agent

Systemd Service

For running as a system service:

[Unit]
Description=VSKI Agent Service

[Service]
Type=simple
Environment="VSKI_CONFIG_DIR=/etc/vski-agent"
Environment="VSKI_DATA_DIR=/var/lib/vski-agent"
Environment="VSKI_LOGS_DIR=/var/log/vski-agent"
ExecStart=/usr/local/bin/vski-agent agent run assistant
User=vski-agent
Group=vski-agent

[Install]
WantedBy=multi-user.target

Troubleshooting

Check Current Configuration

# View all environment settings
vski-agent env

# Check config search paths
vski-agent config path

# Validate configuration
vski-agent config validate

Common Issues

Config file not found

# Check what filename is being searched for
vski-agent env | grep config_filename

# Check search paths
vski-agent config path

Environment variables not loading

# Verify .env file exists and is readable
ls -la .env

# Check for syntax errors
cat .env

# Try loading with verbose mode
vski-agent -v -e .env config list

Wrong configuration being used

# Check priority - command line > env vars > defaults
vski-agent env

# Verify which config file is being loaded
vski-agent config list

Best Practices

Use .env files for project-specific configuration
- Commit .env.example with documented defaults
- Add .env to .gitignore
- Use .env.local for personal overrides
Use environment variables for deployment-specific configuration
- Set in systemd service files
- Set in Docker/Kubernetes manifests
- Set in CI/CD pipelines
Use command-line arguments for one-time overrides
- Quick tests with different configs
- Debugging specific issues
Organize configuration hierarchically
- Global defaults in ~/.config/vski-agent/
- Project-specific configs in project directory
- Environment-specific .env files

Migration from vski-agent.yaml

If you're migrating from the old vski-agent.yaml default:

# Option 1: Keep using old filename (set env var)
export VSKI_AGENT_CONFIG=vski-agent.yaml

# Option 2: Rename to new default
mv vski-agent.yaml agent.config.yaml

# Option 3: Use command-line override
vski-agent --config vski-agent.yaml config list

The new default filename is agent.config.yaml, but all old filenames are still searched as fallbacks.

Environment Configuration