Check Castor version

This document explains how to manage and enforce Castor versions within your projects.

The guard_min_version() function

use function Castor\guard_min_version;

guard_min_version('v0.11.0');

This function will throw an exception if the current version of Castor is lower (e.g. 0.10.0). That will force the user to update Castor before running the command.

This is useful when you want to use a new feature of Castor in your command. In this situation, you want to ensure that the user has the right version of Castor.

Tip

Where to put this function?

It depends on your usage. If you want to ensure that the user has the right version of Castor before running any task, you can put it in the top of your castor.php file.

If you only want to ensure that the user has the right version of Castor before running a specific task, you can put it in the task function directly and check will be done only when the task is called.

You can go further with Events and Listeners to check certain conditions by checking a pattern task name.

Update reminder

When a new version is available, Castor will periodically remind the user to update the tool once in a day.

This behavior can be disabled by setting the CASTOR_DISABLE_VERSION_CHECK environment variable to 1 or true.

AI agent context

Castor automatically detects when it is running inside an AI agent (e.g. Claude Code, GitHub Copilot Workspace, or any environment where STDIN is not a TTY). In that context, Castor reduces its output to avoid polluting the agent's context window: the ASCII logo is hidden and update reminders are suppressed.

If the detection produces a false positive — for instance in a CI pipeline that looks like an agent — you can disable it by setting the CASTOR_DISABLE_AGENT_DETECTION environment variable to any non-empty value:

CASTOR_DISABLE_AGENT_DETECTION=true castor my-task