Skip to content

Installation

This guide will help you install Consoul on your system.

Prerequisites

  • Python 3.10 or higher
  • pip (Python package installer)
  • C compiler (for tree-sitter compilation):
  • macOS: Xcode Command Line Tools (xcode-select --install)
  • Linux: build-essential package (sudo apt-get install build-essential)
  • Windows: Visual Studio Build Tools 2019+ OR MinGW

Installation Methods

Install the latest stable release from PyPI:

# Install with TUI (recommended)
pip install 'consoul[tui]'

# Or install SDK/CLI only
pip install consoul

For development dependencies:

pip install 'consoul[dev]'

From Source

Clone the repository and install in development mode:

# Clone the repository
git clone https://github.com/goatbytes/consoul.git
cd consoul

# Install with Poetry
poetry install --with dev,docs,security

# Or install with pip in editable mode
pip install -e '.[dev]'

Using pipx (Isolated Installation)

For an isolated installation that doesn't affect your system Python:

# Install pipx if you don't have it
python3 -m pip install --user pipx
python3 -m pipx ensurepath

# Install Consoul with TUI
pipx install 'consoul[tui]'

Verify Installation

After installation, verify that Consoul is installed correctly:

# Check version
consoul --version

# Run help to see available commands
consoul --help

Configuration

API Keys

Consoul requires API keys for AI providers. Set them as environment variables:

For Anthropic (Claude): 

export ANTHROPIC_API_KEY="your-api-key-here"

For OpenAI: 

export OPENAI_API_KEY="your-api-key-here"

For Google (Gemini): 

export GOOGLE_API_KEY="your-api-key-here"

Add these to your shell configuration file (~/.bashrc, ~/.zshrc, etc.) to make them permanent:

# Add to ~/.zshrc or ~/.bashrc
echo 'export ANTHROPIC_API_KEY="your-api-key-here"' >> ~/.zshrc
source ~/.zshrc

Configuration File

Create a configuration file at ~/.config/consoul/config.yaml:

# Create config directory
mkdir -p ~/.config/consoul

# Create basic config file
cat > ~/.config/consoul/config.yaml << EOF
provider: anthropic
model: claude-3-5-sonnet-20241022
theme: dark
save_conversations: true
EOF

Troubleshooting

Command Not Found

If you get a "command not found" error after installation:

  1. Ensure pip installs to a directory in your PATH: 

    python3 -m pip install --user consoul

  2. Add Python user bin to your PATH: 

    # For Linux/macOS
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Permission Errors

If you encounter permission errors during installation:

# Use --user flag to install in your home directory
pip install --user consoul

Python Version Issues

If your default python is not 3.10+:

# Install with python3 explicitly
python3 -m pip install consoul

# Or use pyenv to manage Python versions
pyenv install 3.12.3
pyenv global 3.12.3

Missing Dependencies

If you encounter missing dependency errors:

# Upgrade pip
pip install --upgrade pip

# Install with all dependencies
pip install --upgrade consoul

tree-sitter Compilation Errors

If you encounter errors related to tree-sitter compilation:

macOS: 

# Install Xcode Command Line Tools
xcode-select --install

# Verify compiler is available
gcc --version

Linux (Ubuntu/Debian): 

# Install build tools
sudo apt-get update
sudo apt-get install build-essential

# Verify compiler is available
gcc --version

Windows: 

# Install Visual Studio Build Tools from:
# https://visualstudio.microsoft.com/downloads/#build-tools-for-visual-studio-2022

# Or use MinGW
# https://www.mingw-w64.org/

Validation: 

# Test tree-sitter compilation after installing compiler
python -c "from tree_sitter import Language, Parser; print('✓ tree-sitter OK')"

Note: If tree-sitter installation fails, basic text search (grep_search) will still work. Code structure search gracefully degrades without tree-sitter.

Next Steps

Uninstallation

To remove Consoul:

# Standard installation
pip uninstall consoul

# pipx installation
pipx uninstall consoul

To remove configuration files:

rm -rf ~/.config/consoul