Troubleshooting

claude: command not found

Clother requires the Claude Code CLI to be installed before it can launch any provider. If claude is missing, install it first:

curl -fsSL https://claude.ai/install.sh | bash

After installation, restart your shell and verify with:

claude --version

Then run clother install to let Clother locate the binary.

clother: command not found

The directory where Clother was installed is not on your PATH.Check which directory Clother uses:

clother status

Then add that directory to your shell’s PATH. For example, if Clother is installed to ~/.local/bin:

# Add to ~/.bashrc or ~/.zshrc
export PATH="$HOME/.local/bin:$PATH"

Reload your shell:

source ~/.bashrc   # or ~/.zshrc

Alternatively, override the install directory at install time using --bin-dir or CLOTHER_BIN. See the platform support page for default paths.

claude --resume ... does not behave like Clother

The claude shim installed by Clother is not being picked up — your shell may be resolving the original claude binary instead.

Restart your shell to clear any cached binary paths.
Re-run the install to make sure the shim is in place:

clother install

Verify the shim is resolved first:

which claude

The path shown should be inside the Clother bin directory (e.g. ~/.local/bin/claude), not the original Claude install location.

--yolo is not recognized

The --yolo flag is handled by the Clother claude shim. If the flag is not recognized, the shim is not being used.

Restart your shell.
Run clother install to ensure the shim is installed and up to date.
Confirm which claude points to the Clother bin directory.

API key not set

A launcher exited with an error like API key not set because the required secret has not been configured yet.Run the interactive config for the affected provider:

clother config <provider>
# For example:
clother config zai
clother config kimi

You can also run clother config without arguments to pick from a menu.API keys are stored in ~/.local/share/clother/secrets.env (permissions 600).

Testing whether a provider endpoint is reachable

Use clother test to check HTTP connectivity to provider endpoints without starting a full Claude session:

# Test all providers
clother test

# Test a specific provider
clother test zai
clother test kimi

Each result shows whether the endpoint is reachable and the HTTP status code returned. A result of unreachable indicates a network or firewall issue, not necessarily a credentials problem.

Checking what Clother has installed

Run clother status to see the current version, all relevant directories, and the number of active profiles:

clother status

For scripting or CI, use JSON output:

clother status --json

This is also useful when configuring VS Code integration — the Bin path shown is where your launcher binaries live, and you can pass the full path of any launcher to the claudeProcessWrapper setting.

Where are API keys stored?

Clother stores all API keys in:

~/.local/share/clother/secrets.env

The file is created with chmod 600 (readable only by your user). You can view or edit it directly if needed, but the recommended way to update keys is via:

clother config <provider>

Finding the launcher path for VS Code integration

The Claude Code VS Code extension (claudeProcessWrapper setting) requires the full absolute path to a launcher binary.Run clother status to find your bin directory, then append the launcher name:

clother status
# Example output:
# Bin: /home/yourname/.local/bin

Set claudeProcessWrapper to the full path, for example:

/home/yourname/.local/bin/clother-zai

On macOS the bin directory is typically ~/bin:

/Users/yourname/bin/clother-zai

Get Started

Providers

Configuration

Guides

Reference