CLIO Installation Guide

May 30, 2026 ยท View on GitHub

Install CLIO and get to a working first session quickly.

CLIO is a terminal-native AI coding tool. It runs in your shell, uses real tools to work with files and commands, and fits terminal-first workflows. This guide focuses on the fastest path from install to first use.

Table of Contents

  1. Choose Your Install Path
  2. System Requirements
  3. Quick Installation
  4. Docker Installation
  5. Installation Options
  6. First-Time Configuration
  7. Verification
  8. Uninstallation
  9. Troubleshooting
  10. Platform-Specific Notes
  11. Next Steps

Choose Your Install Path

Most people should use one of these:

  • Homebrew - easiest on macOS and Linux with Homebrew installed
  • Standard install - best if you want clio available system-wide
  • User install - best if you do not want to use sudo
  • Docker - best if you want to try CLIO without installing Perl locally

If you already have GitHub Copilot, the fastest path after installation is:

clio --new
/api login

Then open any repository and give CLIO a real task.

System Requirements

Operating System

PlatformStatus
macOS 10.14+Fully Supported
Linux (Ubuntu 18.04+, Debian 10+, Fedora 30+, Arch)Fully Supported
Windows (WSL or Cygwin)Experimental

Required Software

Perl 5.32+ (usually pre-installed on macOS/Linux):

perl --version

Git 2.0+:

git --version

Perl Modules

CLIO uses only core Perl modules - no CPAN dependencies:

  • JSON::PP (core since 5.14)
  • HTTP::Tiny (core since 5.14)
  • MIME::Base64 (core)
  • File::Spec, File::Path (core)
  • Time::HiRes (core)

AI Provider

You need at least one AI provider. See PROVIDERS.md for the full list.

Common choices:

  • GitHub Copilot - easiest starting point, access to multiple models
  • Local models - llama.cpp, LM Studio, or SAM
  • API providers - OpenAI, Google, DeepSeek, OpenRouter, MiniMax, Z.AI

Quick Installation

Homebrew

brew tap SyntheticAutonomicMind/homebrew-SAM
brew install clio

# Clone the repository
git clone https://github.com/SyntheticAutonomicMind/CLIO.git
cd CLIO

# Install system-wide
sudo ./install.sh

# Start CLIO
clio --new

CLIO installs to /opt/clio with a symlink at /usr/local/bin/clio.

User Install (No Sudo)

./install.sh --user

Installs to ~/.local/clio. Ensure ~/.local/bin is in your PATH:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Docker Installation

Run CLIO in a container - no local Perl required:

docker run -it --rm \
    -v "$(pwd)":/workspace \
    -v clio-auth:/root/.clio \
    -w /workspace \
    ghcr.io/syntheticautonomicmind/clio:latest \
    --new

Convenience Wrapper

git clone https://github.com/SyntheticAutonomicMind/CLIO.git
cd CLIO
./clio-container ~/projects/myapp

Image Tags

TagDescription
:latestMost recent stable release
:YYYYMMDD.NSpecific version
:sha-XXXXXXSpecific Git commit

See SANDBOX.md for security details.

Installation Options

OptionCommandLocation
System-wide (default)sudo ./install.sh/opt/clio
Custom directorysudo ./install.sh /usr/local/clio/usr/local/clio
User install./install.sh --user~/.local/clio
No symlinksudo ./install.sh --no-symlink/opt/clio (no PATH)
Custom symlinksudo ./install.sh --symlink /usr/bin/clioCustom symlink path

First-Time Configuration

After installation, start CLIO:

clio --new

This is the easiest way to get started:

/api set provider github_copilot
/api login
# Browser opens -> authorize -> done

OpenAI / Other API Providers

/api set provider openai
/api set key sk-...your-key...
/config save

Local Models (llama.cpp, LM Studio)

# Ensure your local server is running first
/api set provider llama.cpp
# No key needed for local providers

View Configuration

/api show

For detailed provider setup instructions, see PROVIDERS.md.

Verification

Check Installation

# Verify CLIO is in PATH
which clio

# Check help
clio --help

# Verify Perl modules
perl -MJSON::PP -e 'print "OK\n"'
perl -MHTTP::Tiny -e 'print "OK\n"'

Test CLIO

clio --new --input "Hello, what's 2+2?" --exit

Test a real workflow

Inside a repository, try something like:

Read this project and explain how configuration is loaded.

Or:

Find the code path that handles authentication failures.

Uninstallation

# Remove installation
sudo rm -rf /opt/clio
sudo rm /usr/local/bin/clio

# Remove user data (optional)
rm -rf ~/.clio

Troubleshooting

"Permission denied"

# Use sudo for system install
sudo ./install.sh

# Or use user install
./install.sh --user

"perl: command not found"

PlatformInstall Command
macOSbrew install perl
Ubuntu/Debiansudo apt-get install perl
Fedora/RHELsudo dnf install perl
Archsudo pacman -S perl

"Connection refused" or API timeout

If you're behind a corporate proxy or firewall:

# Set proxy for API requests
/config set http_proxy http://proxy.example.com:8080

# Or use environment variables
export HTTPS_PROXY=http://proxy.example.com:8080

CLIO not found after --user install

Make sure ~/.local/bin is in your PATH:

export PATH="$HOME/.local/bin:$PATH"

Add it to your shell profile if needed.

Platform-Specific Notes

macOS

Perl is usually preinstalled. Homebrew installation is the easiest path.

Linux

Most distributions already include Perl and Git. Standard or user install both work well.

Windows

Use WSL for the smoothest experience. Native Windows support is improving, but WSL remains the better option for now.

Next Steps

See Also