README

ray-cli

This package provides a command-line interface for interacting with the Ray application by Spatie.

Supported PHP versions: 7.4, 8.0.

Installation

You may install the package using composer:

composer require permafrost-dev/ray-cli --dev

Also available is a download for a phar executable from the releases page. The primary advantage of using a phar is that you don't need to install the package into your project.

If you download a phar, replace vendor/bin/ray with the filename of the phar in the examples, i.e.:

vendor/bin/ray 'test message' --green --large

would become:

ray-1.6.0.phar 'test message' --green --large

Note: Some users may need to set the phar as executable using chmod. Example: chmod +x ray-1.6.0.phar

Usage

Sending data to Ray is as simple as calling the ray script and providing a single argument, either a string or a filename:

vendor/bin/ray 'hello world'

You can provide a JSON string and Ray will format it for you:

vendor/bin/ray '{"message": "hello world"}'

You're also able to pass a valid filename instead of a string. The contents of the file will be sent instead, with automatic JSON detection.

vendor/bin/ray "testfile.json" -c green
vendor/bin/ray "readme.txt"

You can even pass a valid URL - it will be downloaded and sent to Ray, with automatic JSON detection.

vendor/bin/ray "https://github.com/permafrost-dev/ray-cli" -c green
vendor/bin/ray "https://api.github.com/repos/permafrost-dev/ray-cli"

Available Options

The ray script offers several flags for sending additional payloads to Ray:

--update-check

Arguments: none

Default: false

Description: Checks for an updated version of ray-cli. If specified, all other flags are ignored.

Example:

vendor/bin/ray --update-check

--exec

Arguments: none

Default: false

Description: Treats the argument as a script or executable, executes it, and sends the output to Ray. Supported interpreters for scripts are PHP, Python, and NodeJS. If the file is executable, such as a binary or .sh script, it will also be executed. JSON content is automatically detected.

Example:

# refresh the display of app.log every 5 seconds
vendor/bin/ray --exec "random.sh"
vendor/bin/ray --exec "random-number.php"

--refresh

Arguments: integer or decimal

Default: none

Description: Refreshes the payload display in Ray every N seconds, where N is either a whole number (i.e., 10) or a decimal (i.e., 7.5). If a file is specified, it is re-read every N seconds; if a URL is specified, it is re-retrieved.

Example:

# refresh the display of app.log every 5 seconds
vendor/bin/ray --refresh=5 "storage/logs/app.log"
# ...or refresh every 2.5 seconds
vendor/bin/ray --refresh=2.5 "storage/logs/app.log"

--color or -c

Arguments: string

Default: none

Description: sends a "color" payload along with the data.

Example:

vendor/bin/ray -c red "hello world"

--large or --lg

Arguments: none

Default: false

Description: sends the payload as large-sized text.

Example:

vendor/bin/ray --large "hello world"
vendor/bin/ray --lg "hello world"

--smallor --sm

Arguments: none

Default: false

Description: sends the payload as small-sized text.

Example:

vendor/bin/ray --small "hello world"
vendor/bin/ray --sm "hello world"

--size or -S

Arguments: string

Default: normal

Possible Values: large, lg, small, sm, normal

Description: sends a payload with the specified text size. See --large and --small. Note that while included for completeness, specifying normal is not necessary as it is the default text size.

Example:

vendor/bin/ray -S sm "hello world"
vendor/bin/ray -S large "hello world"
vendor/bin/ray --size=normal "hello world"

--label or -L

Arguments: string

Default: none

Description: sends a "label" payload along with the data. Only works when sending plain (non-JSON and non-delimited) strings.

Example:

vendor/bin/ray -L "my label" "hello world"

--notify or -N

Arguments: none

Default: false

Description: sends a "notification" payload, causing Ray to display an OS notification instead of logging the data in its window.

Example:

vendor/bin/ray -N "hello from ray-cli"

--csv

Arguments: none

Default: false

Description: causes the payload data to be treated as a comma-separated list of values, and will explode() the data and send the resulting array of values instead.

Example:

vendor/bin/ray --csv "one,two,three"

--delimiter or -D

Arguments: string

Default: none

Description: causes the payload data to be treated as a list of values delimited by the provided delimiter string, and will explode() the data and send the resulting array of values instead.

Example:

vendor/bin/ray -D '|' "one|two|three"

--json or -j

Arguments: none

Default: false

Description: Forces the payload data to be treated as a JSON string. Note that this flag is unnecessary in most cases because JSON strings are automatically detected.

Example:

vendor/bin/ray --json '["one","two","three"]'

--stdin

Arguments: none

Default: false

Description: Reads the payload data from the standard input instead of as a command line parameter. Note that the payload data can be specified as as dash ("-") instead of specifying the --stdin flag.

Example:

echo "hello world" | vendor/bin/ray --stdin
echo "hello world" | vendor/bin/ray -

--raw

Arguments: none

Default: false

Description: Forces the payload data be pre-processed and to display the raw, unrendered content. The data is processed to encode HTML entities, spaces, and converts new lines to <br> tags (this is done to display HTML source code).

Example:

cat sample.html | vendor/bin/ray --stdin --raw
vendor/bin/ray --raw sample.html

--screen or -s

Arguments: string

Default: none

Description: causes a new screen to be created in Ray, with the argument being the "name" of the new screen. Passing an empty string or a string value of "-" will cause the screen to be unnamed (the same effect as calling ray()->clearScreen()). Passing --screen or -s as the last argument on the command line is the same as providing a screen name of "-".

Example:

# create a screen named "debug #1":
vendor/bin/ray -s 'debug #1' "hello world"
vendor/bin/ray --screen='debug #1' "hello world"

# create a screen with no name:
vendor/bin/ray -s- "hello world"
vendor/bin/ray --screen=- "hello world"
vendor/bin/ray --screen= "hello world"
vendor/bin/ray "hello world" -s

# create a named screen without sending data:
vendor/bin/ray --screen="my screen 2"
vendor/bin/ray -s "my screen 3"

--clear or -C

Arguments: none

Default: none

Example: Description: causes Ray the clear the screen (it's really just creating a new screen with no name). If both --screen and --clear are provided, --clear takes precedence.

Example:

# clear the screen and send some data:
vendor/bin/ray -C "hello world"
vendor/bin/ray --clear "hello world"

# clear the screen without sending any data:
vendor/bin/ray -C
vendor/bin/ray --clear

--clear-all

Arguments: none

Default: none

Description: causes Ray to clear all screens.

Example:

vendor/bin/ray --clear-all

--image or -i

Arguments: none

Default: none

Description: causes the payload to be treated as an image. The payload must be either a URL or an existing filename.

Example:

vendor/bin/ray --image https://static.permafrost.dev/images/ray-cli/ray-cli-logo-01.png

vendor/bin/ray -i my-image-file.png

--blue, --gray, --green, --orange, --purple, --red

Arguments: none

Default: false

Description: causes the payload to be sent with the indicated color. Alias for the --color=N flag.

Example:

vendor/bin/ray --red "hello world"
vendor/bin/ray --orange "hello world"

# only the first flag is used when multiple flags are provided.
# sent as green:
vendor/bin/ray --green --red --blue "hello world"

--bg-blue, --bg-gray, --bg-green, --bg-orange, --bg-purple, --bg-red

Arguments: none

Default: false

Description: causes the payload to be sent with the indicated background color.

Example:

vendor/bin/ray --bg-purple --large "hello world"

Examples

Send the contents of a JSON file to Ray with a blue marker:

cat my-data.json | vendor/bin/ray --stdin -c blue
vendor/bin/ray 'my-data.json' --blue

Send the contents of test.json with small text, a red marker, and to a new screen named "my data":

vendor/bin/ray --screen='my data' --red --small 'test.json'

Testing

This package uses PHPUnit for unit tests. To run the test suite, run:

./vendor/bin/phpunit

Changelog

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

License

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