• English

    • 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
    Asset FAILEDOnline processing rejected the file.Read the public error; fix the file and ask before a new upload.
    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.