Skip to content


Repository files navigation


Debug cli scripts with Ray to fix problems faster

npm version license test status


This npm package provides a ray script that lets you control Spatie's Ray app from the command line. It allows you to easily debug your CLI scripts.


Install the package normally with npm:

npm install node-ray-cli

...install it globally to be able to access it from any script/directory:

npm install -g node-ray-cli

...or run it without installing using npx:

npx node-ray-cli --help


ray <command name> <args, ...>

If no command name is specified, send is assumed.


When calling commands that send modifiable payloads, the payload uuid is sent to stdout if the --show-uuid option flag is provided. For example, you may modify the color of a payload after it has been sent by using the color command:

ray 'hello world' --show-uuid # writes "ae625128-ed3a-2b92-1a3f-2e0ebf7a2ad1" to stdout
ray color ae625128-ed3a-2b92-1a3f-2e0ebf7a2ad1 green

...or remove the payload from Ray entirely:

ray 'hello world' --show-uuid # writes "ae625128-ed3a-2b92-1a3f-2e0ebf7a2ad1" to stdout
ray remove ae625128-ed3a-2b92-1a3f-2e0ebf7a2ad1

Some other usage examples:

ray 'hello world' --blue
ray pause
ray html '<em>hello world</em>'
ray file message.txt

Disabling node-ray-cli

The ray command can be disabled by setting the NODE_RAY_DISABLED environment variable to "1":


Available option flags

There are several option flags that can be used with any command:

Flag Description
--hide Display the payload as collapsed by default
--if=value Don't send the payload if value is "false", 0, or "no"
--large Display large text
--show-uuid Write the payload uuid to stdout
--small Display small text
--blue Display the payload as blue
--gray Display the payload as gray
--green Display the payload as green
--orange Display the payload as orange
--purple Display the payload as purple
--red Display the payload as red

Command reference

Command Description
clear Clear the current screen
clear-all Clear the current and all previous screens
color <uuid> <color> Change the color of a payload that has already been sent
confetti Display confetti in Ray!
file <filename> Show the contents of filename
hide-app Hide the Ray app
html <content> Display rendered html
image <location> Display an image from a URL or file
json <content> Display formatted JSON
notify <message> Display a desktop notification
pause Pause code execution
remove <uuid> Remove a payload
send <payload> Send a payload to Ray
show-app Show the Ray app
size <uuid> <size> Change the text size of a payload that has already been sent (sizes are 'large' or 'small')
text <data> Display a text string with whitespace preserved
xml <data> Display formatted XML

Example Bash Script


RAYUUID=$(ray "arg count: $#" --show-uuid)
ray color $RAYUUID blue

if [ $# -eq 0 ]; then
    echo "no filename provided"
    exit 1


ray file "$FILENAME" --purple --small --hide
ray show-app

if [ ! -e "$FILENAME" ]; then
    ray send "file missing: $FILENAME" --red
    exit 1

ray pause

cat "$FILENAME" | wc -l

Development Setup

npm install
npm run build:dev
node dist/index.js --help


node-ray-cli uses Jest for unit tests. To run the test suite:

npm run test

Code Coverage

codecov commits graph
codecov sunburst graph


Please see CHANGELOG for more information on what has changed recently.


Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.



The MIT License (MIT). Please see License File for more information.