Fix common HolyCrab CLI problems

Use the section that matches the exact message on your screen. It is safe to share an error message, but remove API Keys, private authorization links, QR codes, names, and private file paths first.

Installation problems

What you seeLikely causeSafe next action
Python is missing or below 3.10The CLI cannot start on that Python version.Install Python 3.12, reopen the terminal, and rerun the installer.
holycrab is not recognized / command not foundThe current terminal has not loaded the user PATH, or installation stopped.Open a new terminal and run holycrab doctor --json (all systems). If the command is still missing, use the system-specific repair commands below.
PowerShell says sh is not recognizedA macOS/Linux command was pasted into Windows.Open the Windows installation guide, copy the command under Install HolyCrab, and run it in PowerShell. This error refers to sh, the Unix shell; it does not require installing SSH.
Doctor reports missing or changed filesA managed file is damaged, missing, or from another version.Rerun the installer to repair, then run doctor again.

When the holycrab command is not found

1. Open a new terminal and check

Open a new PowerShell window on Windows, or a new Terminal window on macOS/Linux. Run the following command; it is the same on all three systems.

holycrab doctor --json

2. Repair the installation if the command is still missing

Only if the terminal still cannot find holycrab, run the official command for your system below. After installation, run holycrab doctor --json again. If installation fails, follow the linked system guide.

Detailed instructions: Windows · macOS / Linux.

Windows PowerShell

irm https://holycrab.ai/cli/install.ps1 | iex

macOS / Linux (Bash / Zsh)

curl -fsSL https://holycrab.ai/cli/install.sh | sh && export PATH="$HOME/.local/bin:$PATH"

API Key and Agent problems

What you seeLikely causeSafe next action
API Key invalidThe Key was copied incorrectly, revoked, or belongs to the wrong account.Confirm an active Key on API Access and run holycrab setup again.
Environment override warningA temporary Key setting is taking priority over the saved Key.Do not paste either Key into chat; follow the OS-specific instruction printed by doctor.
Codex cannot find HolyCrabCodex started before installation or its local connection points to an old path.Rerun the installer once, then start a new Codex task.

Task and upload problems

On a phone, swipe left for the complete recovery action.

What you seeWhat it meansDo this next
A new model or draft option is rejectedThe installed version or selected model may not support it.Check holycrab --version and ask Codex to read the installed model directory. Update if needed, then estimate again.
An asset is unavailable for the chosen modelRequired review or file information is pending, or the file does not meet the model’s requirements.For pending Seedance review, keep checking the same ID. Kling and MiniMax do not need to wait for that review. If the estimate reports pending file information, wait on the same ID; follow the reason for a definite failure.
An asset is being deletedThe asset is unavailable to every model.Choose another existing asset; waiting will not make this one usable.
An existing final failedThat failed task cannot be reused as a successful final.Check the failure reason and draft validity. If conversion is still permitted, review a new quote and approve it before creating another final.
The final quote changedThe latest quote differs from the approved amount.Review and approve the new quote before creating a final.
A draft cannot be convertedIt may have expired or may not be available to the current account.Ask Codex to check the original draft and any linked final, then follow the returned reason.
Task wait timed outThe task may still be processing.Keep the Task ID and wait on the same task again.
Authorization wait timed outThe person has not reached a final state yet.Keep the Authorization ID; do not create another.
Generation/upload result unknownThe online action may already have happened.List/query existing records first. Do not repeat the same paid or upload action.

Useful checks

Show safe diagnostic commands

These commands inspect local status or existing records. They do not approve a paid generation.

holycrab --version
holycrab doctor --json
holycrab doctor --json --online
holycrab tasks list
holycrab generate attempts list

If you still need help

  • Share your operating system, CLI version, the exact command, and the redacted error text.
  • Say whether a Task ID, Asset ID, Group ID, or Authorization ID was returned, but redact private names and links.
  • Never send the API Key. Support does not need it to read an error message.

If it did not work

  • If the same safe repair fails twice, stop and send the redacted error with your OS and CLI version.
  • For an uncertain paid or upload result, wait for a status check instead of experimenting with another submission.