ray-cli
This package provides a command-line interface for interacting with the Ray application by Spatie.
Supported PHP versions: 7.4, 8.0.
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 --largewould become:
ray-1.6.0.phar 'test message' --green --largeNote: Some users may need to set the phar as executable using chmod. Example: chmod +x ray-1.6.0.phar
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"The ray script offers several flags for sending additional payloads to Ray:
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-checkArguments: 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"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"Arguments: string
Default: none
Description: sends a "color" payload along with the data.
Example:
vendor/bin/ray -c red "hello world"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"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"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"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"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"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"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"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"]'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 -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.htmlArguments: 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"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 --clearArguments: none
Default: none
Description: causes Ray to clear all screens.
Example:
vendor/bin/ray --clear-allArguments: 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.pngArguments: 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"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"
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' --blueSend 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'This package uses PHPUnit for unit tests. To run the test suite, run:
./vendor/bin/phpunit
Please see CHANGELOG for more information on what has changed recently.
The MIT License (MIT). Please see License File for more information.