PHPackages                             permafrost-dev/ray-cli - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [CLI & Console](/categories/cli)
4. /
5. permafrost-dev/ray-cli

ActiveProject[CLI & Console](/categories/cli)

permafrost-dev/ray-cli
======================

sends data to Ray via a cli command

1.12.0(5y ago)28759[1 PRs](https://github.com/permafrost-dev/ray-cli/pulls)MITPHPPHP ^7.4|^8.0

Since Jan 10Pushed 2y ago2 watchersCompare

[ Source](https://github.com/permafrost-dev/ray-cli)[ Packagist](https://packagist.org/packages/permafrost-dev/ray-cli)[ RSS](/packages/permafrost-dev-ray-cli/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (10)Dependencies (5)Versions (23)Used By (0)

[![Permafrost Dev](https://camo.githubusercontent.com/bb8b6c0a8a67397a752eeef1855ed6ff79569140c8a1a60a4dafd7a8cc6f910d/68747470733a2f2f7374617469632e7065726d6166726f73742e6465762f696d616765732f7261792d636c692f7261792d636c692d6c6f676f2d30312e706e67)](https://camo.githubusercontent.com/bb8b6c0a8a67397a752eeef1855ed6ff79569140c8a1a60a4dafd7a8cc6f910d/68747470733a2f2f7374617469632e7065726d6166726f73742e6465762f696d616765732f7261792d636c692f7261792d636c692d6c6f676f2d30312e706e67)

 `ray-cli`

[![version](https://camo.githubusercontent.com/3c8367ff8f1469a9dc31e49805f1c9d75f41492b39ea1989fb7bce1e943995c3/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f7065726d6166726f73742d6465762f7261792d636c69)](https://camo.githubusercontent.com/3c8367ff8f1469a9dc31e49805f1c9d75f41492b39ea1989fb7bce1e943995c3/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f7065726d6166726f73742d6465762f7261792d636c69) [![license](https://camo.githubusercontent.com/0f4bf1dac0c57d21fdeb9b7088ce563bd19111fe318fb4380a5236cf70f251d0/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f7065726d6166726f73742d6465762f7261792d636c69)](https://camo.githubusercontent.com/0f4bf1dac0c57d21fdeb9b7088ce563bd19111fe318fb4380a5236cf70f251d0/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f7065726d6166726f73742d6465762f7261792d636c69) [![downloads](https://camo.githubusercontent.com/c65b18d3e5e690bddf3cfba16e35f9e82d16133630672f90c554f0f37a74d0dc/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f7065726d6166726f73742d6465762f7261792d636c693f6c6f676f3d7061636b6167697374)](https://camo.githubusercontent.com/c65b18d3e5e690bddf3cfba16e35f9e82d16133630672f90c554f0f37a74d0dc/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f7065726d6166726f73742d6465762f7261792d636c693f6c6f676f3d7061636b6167697374) [![Run Tests](https://camo.githubusercontent.com/b212abb1eb6d1170140291fd5ceddc1e2e3aade4ba168b0bb09c3d6e686be628/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f776f726b666c6f772f7374617475732f7065726d6166726f73742d6465762f7261792d636c692f52756e25323054657374732f6d61696e3f6c6f676f3d676974687562)](https://camo.githubusercontent.com/b212abb1eb6d1170140291fd5ceddc1e2e3aade4ba168b0bb09c3d6e686be628/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f776f726b666c6f772f7374617475732f7065726d6166726f73742d6465762f7261792d636c692f52756e25323054657374732f6d61696e3f6c6f676f3d676974687562) [![Coverage Status](https://camo.githubusercontent.com/78e36f443f744ad3cb7c363622407120f6ce4cb6b2630bba1c91da4e0b970c9f/68747470733a2f2f736869656c64732e696f2f636f766572616c6c732f6769746875622f7065726d6166726f73742d6465762f7261792d636c69)](https://camo.githubusercontent.com/78e36f443f744ad3cb7c363622407120f6ce4cb6b2630bba1c91da4e0b970c9f/68747470733a2f2f736869656c64732e696f2f636f766572616c6c732f6769746875622f7065726d6166726f73742d6465762f7261792d636c69)

This package provides a command-line interface for interacting with the [Ray](https://myray.app) application by [Spatie](https://github.com/spatie).

---

Supported PHP versions: `7.4`, `8.0`.

Installation
------------

[](#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](https://github.com/permafrost-dev/ray-cli/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
-----

[](#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"}'`

 [![Decoded JSON](https://camo.githubusercontent.com/6ca60ed43b4f6c4309fc6a75c5fe2a869735c9b665e526d3e66bdfd7fbb12c29/68747470733a2f2f7374617469632e7065726d6166726f73742e6465762f696d616765732f7261792d636c692f6a736f6e2d6465636f6465642e706e67)](https://camo.githubusercontent.com/6ca60ed43b4f6c4309fc6a75c5fe2a869735c9b665e526d3e66bdfd7fbb12c29/68747470733a2f2f7374617469632e7065726d6166726f73742e6465762f696d616765732f7261792d636c692f6a736f6e2d6465636f6465642e706e67)

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

[](#available-options)

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

### `--update-check`

[](#--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`

[](#--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`

[](#--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`

[](#--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`

[](#--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"
```

### `--small`or `--sm`

[](#--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`

[](#--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`

[](#--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`

[](#--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`

[](#--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`

[](#--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`

[](#--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`

[](#--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`

[](#--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 `` 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`

[](#--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`

[](#--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`

[](#--clear-all)

Arguments: `none`

Default: `none`

Description: causes Ray to clear all screens.

Example:

```
vendor/bin/ray --clear-all
```

### `--image` or `-i`

[](#--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`
--------------------------------------------------------------

[](#--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`
--------------------------------------------------------------------------------

[](#--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"
```

 [![Purple Background](https://camo.githubusercontent.com/feefe68d157cc5358cac182893864e82caa476c8389758573ace66b1f5477af6/68747470733a2f2f7374617469632e7065726d6166726f73742e6465762f696d616765732f7261792d636c692f776974682d6261636b67726f756e642d636f6c6f722e706e67)](https://camo.githubusercontent.com/feefe68d157cc5358cac182893864e82caa476c8389758573ace66b1f5477af6/68747470733a2f2f7374617469632e7065726d6166726f73742e6465762f696d616765732f7261792d636c692f776974682d6261636b67726f756e642d636f6c6f722e706e67)

---

Examples
--------

[](#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
-------

[](#testing)

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

`./vendor/bin/phpunit`

---

Changelog
---------

[](#changelog)

Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.

---

License
-------

[](#license)

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

###  Health Score

34

—

LowBetter than 77% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity25

Limited adoption so far

Community10

Small or concentrated contributor base

Maturity68

Established project with proven stability

 Bus Factor1

Top contributor holds 98.9% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~1 days

Total

21

Last Release

1932d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/de8dcb8e8a47ddc1076a26721d1ce7b17e3066b53c4a5c5e9aa31367c1955a20?d=identicon)[permafrost-dev](/maintainers/permafrost-dev)

---

Top Contributors

[![patinthehat](https://avatars.githubusercontent.com/u/5508707?v=4)](https://github.com/patinthehat "patinthehat (90 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (1 commits)")

---

Tags

clidebuggingdebugging-toolspharrayray-clispatierayclipermafrost

###  Code Quality

TestsPHPUnit

Code StylePHP CS Fixer

### Embed Badge

![Health badge](/badges/permafrost-dev-ray-cli/health.svg)

```
[![Health](https://phpackages.com/badges/permafrost-dev-ray-cli/health.svg)](https://phpackages.com/packages/permafrost-dev-ray-cli)
```

###  Alternatives

[nunomaduro/collision

Cli error handling for console/command-line PHP applications.

4.6k331.8M8.5k](/packages/nunomaduro-collision)[nunomaduro/termwind

It's like Tailwind CSS, but for the console.

2.5k239.8M286](/packages/nunomaduro-termwind)[helhum/typo3-console

A reliable and powerful command line interface for TYPO3 CMS

2939.0M192](/packages/helhum-typo3-console)[buggregator/trap

A simple and powerful tool for debugging PHP applications.

2591.7M40](/packages/buggregator-trap)[laminas/laminas-cli

Command-line interface for Laminas projects

563.7M54](/packages/laminas-laminas-cli)[phpcr/phpcr-utils

PHP Content Repository implementation independant utilities

743.2M14](/packages/phpcr-phpcr-utils)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)