curs_overlay - Linux


curs_overlay is a command-line utility for creating and managing overlays in the Linux console. It allows users to superimpose text, images, and arbitrary graphics on top of the active display. This command is essential for debugging, presentation, and assistive technologies.


curs_overlay [-h] [-o OPAQUE] [-p POS] [-s SIZE] [-f FONT] [-c COLOR] [-t TEXT] [-i IMAGE]


  • -h, –help: Display usage information.
  • -o, –opaque: Set the overlay’s opacity (0-255). Default: 255 (fully opaque).
  • -p, –position: Specify the overlay’s position on the display (+X+Y format). Default: Centered.
  • -s, –size: Set the overlay’s size in pixels (WIDTHxHEIGHT format).
  • -f, –font: Select the font for text overlays.
  • -c, –color: Set the foreground color for text overlays.
  • -t, –text: Display specified text on the overlay.
  • -i, –image: Overlay the specified image file.


Simple text overlay:

curs_overlay -t "Debug Info"

Centered opaque overlay with custom size:

curs_overlay -p +200+200 -o 128 -s 800x400

Overlay an image with 50% opacity:

curs_overlay -i image.png -o 127

Common Issues

  • Overlays not visible: Ensure the overlay is not obstructed by another window or the cursor.
  • Incorrect positioning: Use the -p option to adjust the overlay’s position.
  • Transparency issues: Adjust the overlay’s opacity using the -o option.


curs_overlay can be combined with other commands to enhance functionality:

# Create an overlay from a terminal session and display it for 10 seconds
script -q /tmp/session.log & (sleep 10 && kill $!; curs_overlay -t "Session Log" -i /tmp/session.log)

Related Commands

  • overlayctl: Advanced overlay management tool.
  • XOverlay: X Window System overlay extension.