Skip to content

Latest commit

 

History

History
252 lines (175 loc) · 8.01 KB

README.md

File metadata and controls

252 lines (175 loc) · 8.01 KB
Raw

Sequin

Charm Sequin Logo
Latest Release Build Status

Human-readable ANSI sequences.

Sequin is a small utility that can help you debug your CLIs and TUIs. It's also great for describing escape sequences you might not understand, and exploring what TUIs are doing under the hood.

There are lots more use cases too, like inspecting golden files such as the ones used by teatest to crystalize Bubble Tea output.

Are you using Sequin in an interesting way? We’d love to hear about it.

Installation

Use a package manager:

# macOS or Linux
brew install charmbracelet/tap/sequin

# Arch Linux (btw)
yay -S sequin-bin

# Nix
nix-shell -p nur.repos.charmbracelet.sequin
Debian/Ubuntu 
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://repo.charm.sh/apt/gpg.key | sudo gpg --dearmor -o /etc/apt/keyrings/charm.gpg
echo "deb [signed-by=/etc/apt/keyrings/charm.gpg] https://repo.charm.sh/apt/ * *" | sudo tee /etc/apt/sources.list.d/charm.list
sudo apt update && sudo apt install sequin
Fedora/RHEL 
echo '[charm]
name=Charm
baseurl=https://repo.charm.sh/yum/
enabled=1
gpgcheck=1
gpgkey=https://repo.charm.sh/yum/gpg.key' | sudo tee /etc/yum.repos.d/charm.repo
sudo yum install sequin

Or, download it:

  • Packages are available in Debian and RPM formats
  • Binaries are available for Linux, macOS, Windows, FreeBSD, OpenBSD, and NetBSD

Or, just install it with go:

go install github.com/charmbracelet/sequin@latest
Shell Completions

All the packages and archives come with pre-generated completion files for Bash, ZSH, Fish, and PowerShell.

If you built it from source, you can generate them with:

sequin completion bash -h
sequin completion zsh -h
sequin completion fish -h
sequin completion powershell -h

If you use a package (like Homebrew, Debs, etc), the completions should be set up automatically, given your shell is configured properly.

Examples

Describing escape sequences

Just use printf to send some sequences to sequin for an explanation.

printf "\x1b[38;5;4mCiao, \x1b[1;7mBaby.\x1b[0m\n" | sequin

Sequin with printf

Reading the output of a program

You can also use it to check the output of any program, for instance, ls or git.

ls -1 --color=always | sequin

git -c status.color=always status -sb | sequin

So yeah, it’s great for debugging applications, and of course, learning about ANSI!

Note

Many programs render their output as plain text when output isn't a terminal (i.e. when redirecting to a file or piping to a program, like sequin). This is a good thing, except in this case when we actually want ANSI sequences so we can inspect them. Thankfully there are usually ways to force colors, like by setting CLICOLOR_FORCE=1 or with flags to force ANSI output. If you're not seeing sequences be sure to to check what works in the case of your specific program.

Examining golden files

Golden file for TUIs contain ANSI, which can be easily inspected with sequin:

cat ./testdata/MyCuteApp.golden | sequin

To generate golden files for your TUIs have a look at golden and teatest from the /x project.

Fake TTY - executing commands

You can also execute commands directly in sequin:

sequin -- ls -1 go.*

Pro Mode: Syntax Highlighting for Raw Sequences

One of the pain points that we find when reading raw ANSI output is that it’s hard to visually separate sequences from regular text. For situations like this you can use the --raw/-r flag to simply highlight sequences inline:

git -c status.color=always status -sb | sequin -r && echo

How it all works

Sequin relies heavily on our glorious ansi package, currently in the elusive /x project. Whilst traversing the strings, Sequin pretty prints what the sequences are and what they’re doing.

Is it done?

No! Common sequences are implemented, but there is still plenty of work to do. For instance, APC sequences are not supported yet. If you notice one of such missing sequences, or want to work on any other area of the project, feel free to open a PR. 💘

FAQ

Why isn't sequin using my terminal's background color? (with multiplexer) related: #28

Check your multiplexer's version

Tmux

This could be a few things depending on your environment. First thing to consider: are you using a terminal multiplexer (e.g. tmux)? If so, check your tmux version is 3.4 or higher. (Tmux added support for OSC10/11 queries in 3.4 see https://github.com/tmux/tmux/blob/master/CHANGES#L152). Not sure which version of tmux you're using? tmux -V

GNU Screen

If you're a GNU screen user, check that your version is 4.99.0 or higher to ensure OSC10/11 can be used. Not sure which version of screen you're using? screen --version

Check your config

Make sure your multiplexer config has your default terminal and COLORTERM set.

tmux.conf

set -g default-terminal "xterm-ghostty"
setenv -g COLORTERM "truecolor"

~/.screenrc

term xterm-256color
setenv COLORTERM truecolor
defbce on

Note: if you don't set defbce on, you will get a different background color on cells cleared with an erase/insert/scroll/clear operation in the regular background color.

Contributing

We love contributions. We recommend checking out our contribution guidelines for faster responses on our end.

Feedback

We’d love to hear your thoughts on this project. Feel free to drop us a note.

License

MIT

Part of Charm.

The Charm logo

Charm热爱开源 • Charm loves open source