node-ray-cli

Debug cli scripts with Ray to fix problems faster

---

Overview

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.

Installation

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

Usage

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":

export NODE_RAY_DISABLED="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

#!/bin/bash

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

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

FILENAME="$1"

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

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

ray pause

cat "$FILENAME" | wc -l

Development Setup

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

Testing

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

npm run test

---

Code Coverage

---

Changelog

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

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

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

Credits

• Patrick Organ
• All Contributors

License

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