PHPackages                             decodelabs/terminus - 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 &amp; Console](/categories/cli)
4. /
5. decodelabs/terminus

ActiveLibrary[CLI &amp; Console](/categories/cli)

decodelabs/terminus
===================

Simple CLI interactions

v0.14.6(5mo ago)424.0k↓100%MITPHPPHP ^8.4CI passing

Since Oct 28Pushed 3mo ago2 watchersCompare

[ Source](https://github.com/decodelabs/terminus)[ Packagist](https://packagist.org/packages/decodelabs/terminus)[ RSS](/packages/decodelabs-terminus/feed)WikiDiscussions develop Synced today

READMEChangelog (10)Dependencies (6)Versions (64)Used By (0)

Terminus
========

[](#terminus)

[![PHP from Packagist](https://camo.githubusercontent.com/76f0f6a642b48300179b1689d6d4033234e234957af315bd1d6cf1c909a4a749/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f6465636f64656c6162732f7465726d696e75733f7374796c653d666c6174)](https://packagist.org/packages/decodelabs/terminus)[![Latest Version](https://camo.githubusercontent.com/570c43df5b113c5ebc38b18bcd35e105391ef2761c434e3645ec492320b85cca/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6465636f64656c6162732f7465726d696e75732e7376673f7374796c653d666c6174)](https://packagist.org/packages/decodelabs/terminus)[![Total Downloads](https://camo.githubusercontent.com/814b63405374056d5316a66d2d355101f5e5923d9029894845e9bf8cad3499a4/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6465636f64656c6162732f7465726d696e75732e7376673f7374796c653d666c6174)](https://packagist.org/packages/decodelabs/terminus)[![GitHub Workflow Status](https://camo.githubusercontent.com/819d98eaa4a597bfb69b9e52c49ac6ec62b00a7ed184df6f9550dedbaa6a5856/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f6465636f64656c6162732f7465726d696e75732f696e746567726174652e796d6c3f6272616e63683d646576656c6f70)](https://github.com/decodelabs/terminus/actions/workflows/integrate.yml)[![PHPStan](https://camo.githubusercontent.com/e25c14ce011edabdd0fbd2e10415b41cc5d66ed11ef3e5b7edd074c5bdd35a2d/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048505374616e2d656e61626c65642d3434434331312e7376673f6c6f6e6743616368653d74727565267374796c653d666c6174)](https://github.com/phpstan/phpstan)[![License](https://camo.githubusercontent.com/732c96d9bf8f356d41f00d169460300d73523798f184e3d67dccf3d8f18ba25a/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f6465636f64656c6162732f7465726d696e75733f7374796c653d666c6174)](https://packagist.org/packages/decodelabs/terminus)

### Simple CLI interactions for PHP

[](#simple-cli-interactions-for-php)

Terminus provides everything you need to build highly interactive, beautiful CLI processes.

---

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

[](#installation)

This package requires PHP 8.4 or higher.

Install via Composer:

```
composer require decodelabs/terminus
```

Usage
-----

[](#usage)

### Writing output

[](#writing-output)

Write standard text to output:

```
use DecodeLabs\Terminus\Session;

$io = Session::getDefault();

$io->$write('Normal text'); // no newline
$io->writeLine(' - end of line'); // with newline
```

Error output works the same way, with `Error` in the method name:

```
$io->writeError('Error text'); // no newline
$io->writeErrorLine(' - end of line'); // with newline
```

### Reading input

[](#reading-input)

Read input from the user: Note, PHP by default buffers the input stream so input requires return to be pressed before it can be read.

```
$data = $io->read(3); // Read 3 bytes
$line = $io->readLine();
```

If the connected terminal supports `stty` (most Unix emulators), buffering can be turned off for instant input:

```
$io->toggleInputBuffer(false);
$io->writeLine('Yes or no?')
$char = $io->read(1); // y or n
$io->toggleInputBuffer(true);
```

More on extended `ANSI` and `stty` support below.

### Colors and styles

[](#colors-and-styles)

If the connected terminal can support `ANSI` codes can be styled easily using a handy shortcut on the facade:

```
$io->{'blue'}('This is blue ');
$io->{'yellow'}('This is yellow ');
$io->{'red|green|underline'}(' This is red on green, underlined');
$io->{'+'}('This starts on a new line');
$io->{'.'}('- this ends on a new line');
$io->{'>>'}('This is tabbed, twice!');
$io->{'..:146|#CCC|bold|underline'}('A whole mix of parameters');
```

Support for `ANSI` codes can be checked with:

```
if($io->isAnsi()) {
    // do stuff
}
```

The format of the style prefix is as follows:

`foreground?|background?|option1?|option2?...`

Modifiers are applied as many times as they appear sequentially.

- Modifiers:
    - `^` Clear line(s) above
    - `+` Add lines before
    - `.` Add lines after
    - `>` Add tabs before
    - `newLine(); // Write to a new line
$io->newLine(5); // Write 5 new lines
$io->deleteLine(); // Delete the previous line
$io->clearLine(); // Clear the current line
$io->clearLineBefore(); // Clear the current line from cursor to start
$io->clearLineAfter(); // Clear the current line from cursor to end
$io->backspace(); // Clear the previous character
$io->tab(); // Write \t to output

$io->cursorUp(); // Move cursor up vertically
$io->cursorLineUp(); // Move cursor up to start of previous line
$io->cursorDown(); // Move cursor down vertically
$io->cursorLineDown(); // Move cursor down to start of next line
$io->cursorLeft(); // Move cursor left
$io->cursorRight(); // Move cursor right

$io->setCursor(5); // Set cursor horizontally to index 5
$io->setCursorLine(30, 10); // Set absolute cursor position

[$line, $pos] = $io->getCursor(); // Attempt to get absolute cursor position
$pos = $io->getCursorH(); // Attempt to get horizontal cursor position
$line = $io->getCursorV(); // Attempt to get vertical cursor position

$io->saveCursor(); // Store cursor position in terminal memory
$io->restoreCursor(); // Attempt to restore cursor position from terminal memory

$width = $io->getWidth(); // Get line width of terminal
$height = $io->getHeight(); // Get line height of terminal
```

### stty

[](#stty)

Some extended functionality is dependent on `stty` being available (most Unix emulators).

```
$io->toggleInputEcho(false); // Hide input characters
$io->toggleInputBuffer(false); // Don't wait on return key for input
```

`stty` can be controlled with the following methods:

```
if($io->hasStty()) {
    $snapshot = $io->snapshotStty(); // Take a snapshot of current settings
    $io->toggleInputEcho(false);
    // do some stuff

    $io->restoreStty($snapshot); // Restore settings
    // or
    $io->resetStty(); // Reset to original settings at the start of execution
}
```

### Widgets

[](#widgets)

Simplify common use cases with built in widgets:

#### Question

[](#question)

```
$answer = $io->newQuestion(
        message: 'How are you?',
        options: ['Great', 'Fine', 'OK'],
        default: 'great'
    )
    ->prompt();

// Or direct..
$answer = $io->ask(
    message: 'How are you?',
    default: 'great'
);

$io->{'..green'}('You are: '.$answer);
```

#### Password

[](#password)

```
$password = $io->newPasswordQuestion(
        message: 'Now enter a password...',
        repeat: true,
        required: true,
    )
    ->prompt();

// Or direct
$password = $io->askPassword(
    message: 'Now enter a password...',
    repeat: true,
    required: true
);

$io->{'..green'}('Your password is: '.$password);
```

#### Confirmation

[](#confirmation)

```
if ($io->confirm(
    message: 'Do you like green?',
    default: true
)) {
    $io->{'..brightGreen'}('Awesome!');
} else {
    $io->{'..brightRed'}('Boo!');
}
```

#### Spinner

[](#spinner)

```
$io->{'.'}('Progress spinner: ');
$spinner = $io->newSpinner();

for ($i = 0; $i < 60; $i++) {
    usleep(20000);
    $spinner->advance();
}

$spinner->complete('Done!');
```

#### Progress bar

[](#progress-bar)

```
$io->{'.'}('Progress bar: ');
$spinner = $io->newProgressBar(
    min: 10,
    max: 50
);

for ($i = 0; $i < 80; $i++) {
    usleep(20000);
    $spinner->advance(($i / 2) + 11);
}

$spinner->complete();
```

### Use Terminus as a PSR Logger

[](#use-terminus-as-a-psr-logger)

```
$io->debug('This is a debug');
$io->info('This is an info message');
$io->notice('This is a notice');
$io->success('You\'ve done a success, well done!');
$io->warning('This is a warning');
$io->error('Hold tight, we have an error');
$io->critical('This is CRITICAL');
$io->alert('alert alert alert');
$io->emergency('Oh no this is an emergency!');
```

### Session

[](#session)

Terminus will by default create a standard session communicating via PHP's `STDIN`, `STDOUT` and `STDERR` streams.

You can however customise the session by creating your own and setting it via the main `Terminus` frontage. See [Deliverance Broker](https://github.com/decodelabs/atlas) for more information about controlling IO streams.

```
use DecodeLabs\Deliverance;
use DecodeLabs\Terminus\Session;

$io = new Session(
    // The Io Broker is optional, defaults to best fit
    Deliverance::newIoBroker()
        ->addInputProvider($inputStream)
        ->addOutputReceiver($outputStream)
        ->addErrorReceiver($errorStream)
);
```

Licensing
---------

[](#licensing)

Terminus is licensed under the MIT License. See [LICENSE](./LICENSE) for the full license text.

###  Health Score

52

↑

FairBetter than 97% of packages

Maintenance75

Regular maintenance activity

Popularity27

Limited adoption so far

Community8

Small or concentrated contributor base

Maturity79

Established project with proven stability

 Bus Factor1

Top contributor holds 100% 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 ~35 days

Recently: every ~0 days

Total

62

Last Release

178d ago

PHP version history (5 changes)v0.5.0PHP ^7.2

v0.6.0PHP ^7.2|^8.0

v0.8.0PHP ^8.0

v0.10.2PHP ^8.1

v0.11.0PHP ^8.4

### Community

Maintainers

![](https://www.gravatar.com/avatar/8a241d64d12b3b5ee94197862ec1ec30b82ed2efa34a0cd7f4c3565a021daddd?d=identicon)[betterthanclay](/maintainers/betterthanclay)

---

Top Contributors

[![betterthanclay](https://avatars.githubusercontent.com/u/1273586?v=4)](https://github.com/betterthanclay "betterthanclay (340 commits)")

---

Tags

cliconsolephpterminalcliterminal

### Embed Badge

![Health badge](/badges/decodelabs-terminus/health.svg)

```
[![Health](https://phpackages.com/badges/decodelabs-terminus/health.svg)](https://phpackages.com/packages/decodelabs-terminus)
```

###  Alternatives

[symfony/console

Eases the creation of beautiful and testable command line interfaces

9.8k1.1B10.0k](/packages/symfony-console)[league/climate

PHP's best friend for the terminal. CLImate allows you to easily output colored text, special formats, and more.

1.9k13.8M250](/packages/league-climate)[php-school/cli-menu

A command line menu helper in PHP

2.0k1.1M22](/packages/php-school-cli-menu)[php-tui/php-tui

Comprehensive TUI library heavily influenced by Ratatui

571637.0k4](/packages/php-tui-php-tui)[aplus/cli

Aplus Framework CLI Library

2301.7M5](/packages/aplus-cli)[splitbrain/php-cli

Easy command line scripts for PHP with opt parsing and color output. No dependencies

176801.1k27](/packages/splitbrain-php-cli)

PHPackages © 2026

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