sequin

If you installed Sequin from source, you can generate completion files for your shell. If you used a package manager like Homebrew or Deb, completions should be set up automatically if your shell is configured correctly.

Available shells:

• Bash
• ZSH
• Fish
• PowerShell

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

Sequin is a utility that takes ANSI escape sequences (from STDIN, a file, or a command's output) and provides a human-readable explanation of what those sequences do. It breaks down sequences like CSI, DCS, OSC, and control characters into understandable text.

Common Usage Patterns

Explain sequences from STDIN: Pipe output from another command into sequin.

Explain sequences from a file: Redirect a file into sequin.

Run a command and explain its output: Pass a command as arguments to sequin to intercept and explain its output.

# Explain sequences from STDIN:
printf '\x1b[m' | sequin

# Explain sequences from a file:
sequin < file

# Run a command and explain its output:
sequin -- some command to execute

You can use Sequin to get a human-readable explanation of specific ANSI escape sequences by piping them into the utility. This is useful for debugging or learning how sequences work.

Note: When piping output from programs, you may need to force ANSI output (e.g., using CLICOLOR_FORCE=1 or specific CLI flags) because many programs strip color when they detect they are not running in a TTY.

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

Pipe the output of any command into Sequin to see the underlying ANSI sequences used for coloring and formatting. Ensure the command is configured to always output color/ANSI sequences.

ls -1 --color=always | sequin

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

Sequin can act as a wrapper to execute a command directly, simulating a TTY environment to inspect the output.

sequin -- ls -1 go.*

If you are using tools like teatest to capture TUI output in "golden files", you can use Sequin to inspect the ANSI sequences contained within those files.

cat ./testdata/MyCuteApp.golden | sequin

You can control the visual theme used for the explanations by setting the SEQUIN_THEME environment variable.

Supported theme values include:

• ansi
• carlos
• secret_carlos
• matchy

If no valid theme is provided or the variable is unset, sequin defaults to a charmTheme that automatically detects whether your terminal has a dark or light background.

By default, Sequin describes sequences. If you want to see the regular text with the ANSI sequences highlighted inline (making it easier to separate text from sequences), use the --raw or -r flag.

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

The handleNotify function is a handler designed to process ANSI escape sequences specifically for terminal notifications. It expects the parser data to contain two parts separated by a semicolon (;). The first part is treated as a prefix, and the second part is extracted to create a formatted string: Notify "<part2>". If the data does not contain exactly two parts, it returns an error.

// Example usage pattern for handleNotify
func handleNotify(p *ansi.Parser) (string, error) {
	parts := bytes.Split(p.Data(), []byte{';'})
	if len(parts) != 2 {
		// Invalid, ignore
		return "", errInvalid
	}

	return fmt.Sprintf("Notify %q", parts[1]), nil
}

The handleFinalTerm function processes ANSI escape sequences used for shell integration (specifically the finalterm sequence). It parses a semicolon-delimited byte slice from an ansi.Parser and returns a human-readable description of the terminal state change.

Sequence Format

The input data must follow the pattern [prefix];[type][;extra_info].

Supported Types

Exit Codes

For type D (Command finished), if a third part is provided in the sequence (e.g., ;D;0), the function appends the exit code to the description: Command finished, exit code: 0.

func handleFinalTerm(p *ansi.Parser) (string, error)