Troubleshooting

Troubleshooting

ai-config: command not found

The install puts the binary in a user bin directory that may not be on PATH.

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

# Find where pip put it
python -m site --user-base

On Windows, add %USERPROFILE%\AppData\Roaming\Python\Scripts to PATH.

Permission errors during install

# Install to the user directory
pip install --user universal-ai-config

# Or use an isolated environment
pipx install universal-ai-config

Migration problems

# See what was detected
ai-config status

# Migrate providers one at a time
ai-config migrate devin

# Verify afterwards
ai-config validate

Originals are backed up as *.backup files. See Migration for rollback steps.

Validation failures

ai-config validate prints each failing check. Common fixes:

• Missing directories: run ai-config init
• Missing keys in config.json: add shared, providers, context_servers, skills (an empty object/list is fine)
• Invalid JSON: fix the syntax in ~/.agents/config/config.json

Project commands fail outside a repo

init-project and migrate --project require a git repository (they locate the root via .git or .ai). Initialize git first or run from inside the project.

SecurityWarning: Skipping untrusted project config

When resolving project configuration, ai-config only loads .ai/ directories that are owned by the current user (the .ai directory itself and its parent). This prevents configuration injection in shared or world-writable directories such as /tmp — another user could otherwise plant a config.json or mcp-config.json that merges into your settings and gets exported to provider files.

If you see this warning:

• You are running ai-config from a directory owned by someone else (e.g. a shared workspace).
• Move into a directory you own, or pass explicit paths instead of relying on project discovery.

On Windows, ownership cannot be verified, so configs load with a warning instead of being skipped.

Clean reinstall

# Uninstall (keeps ~/.agents by default; add --remove-config to wipe it)
curl -fsSL https://raw.githubusercontent.com/DevArtsLab/tool-universal-ai-config/main/uninstall.sh | bash

# Reinstall
curl -fsSL https://raw.githubusercontent.com/DevArtsLab/tool-universal-ai-config/main/install.sh | bash

Still stuck

Open an issue: https://github.com/DevArtsLab/tool-universal-ai-config/issues

Include ai-config status and ai-config validate output plus your OS and Python version.