SKYCHAT(1)

NAME
skychat - terminal client for skych.at

SYNOPSIS
skychat [username [password]] [--debug]

DESCRIPTION
skychat is a curses-based terminal client for the SkyChat chat service at skych.at. It provides a three-panel layout with a channel list, chat view, and user list, and supports inline image preview via Kitty, Sixel, or libcaca protocols.

Without arguments, an interactive login screen is shown with the username pre-filled from the saved config if available. Credentials can also be passed directly on the command line to skip the login screen.

OPTIONS

username
    Username to log in with. If omitted, the login screen is shown.

password
    Password to log in with. Required if username is given.

--debug
    Write crash tracebacks and debug logs to /tmp/skychat_crash.log and /tmp/skychat_debug.log instead of silently exiting.

ENVIRONMENT

SKYCHAT_URL
    WebSocket server URL to connect to. Defaults to wss://skych.at/api/ws. Useful for self-hosted instances.

ESCDELAY
    ncurses ESC disambiguation delay in milliseconds. Automatically set to 25 by the client to reduce latency.

LAYOUT

The interface is divided into three vertical panels:

┌──────────┬─────────────────────────┬──────────┐
│ Channels │      Chat messages      │  Users   │
│          ├─────────────────────────┤          │
│          │    Input box            │          │
└──────────┴─────────────────────────┴──────────┘

Tab cycles focus between panels. The active panel is indicated by a ▶ in its title.

KEYS

  Navigation

Tab/Shift+Tab
    Cycle focus: Input → Rooms → Users → Input.

↑/↓ (Rooms focus)
    Move room cursor.

Enter (Rooms focus)
    Join selected room.

Backspace (Rooms focus)
    Leave selected DM or private room.

↑/↓ (Users focus)
    Move user cursor.

Enter (Users focus)
    Open DM with selected user.

  Messages (Input focus)

↑/↓ Enter scroll mode and move message selection.

Shift+↑
    Scroll up 5 messages.

Shift+↓
    Snap back to the bottom.

Space (while scrolled)
    Quote selected message — prefills @<id> in the input box.

e (while scrolled)
    Edit selected message (own messages only).

Backspace (while scrolled)
    Delete selected message (own messages only).

< / > (while scrolled)
    Cycle between URLs and buttons in the selected message.

o (while scrolled)
    Open focused URL with the configured URL opener, or activate focused button.

Esc Close image preview if open (then open menu), otherwise toggle menu.

  Input Editing

⟨/⟩ Move cursor left or right.

Home/End
    Jump to start or end of input.

Backspace/Del
    Delete character.

Enter
    Send message.

Alt+Enter / Shift+Enter
    Insert a newline (compose multi-line messages).

The input box grows up to 5 lines and shrinks back after sending. Lines beginning with > are rendered as greentext.

  Image Preview

When a message is selected in scroll mode and the focused link is an image URL, a preview popup appears automatically after a short hover delay.

H or Esc
    Hide popup (suppressed until focus moves to a different URL). Esc also opens the menu.

O   Open the image URL with the configured URL opener.

< / >
    Cycle to the previous or next link in the message.

SLASH COMMANDS

/quit
    Exit the client.

/join id
    Join room by numeric ID.

/rooms
    List available rooms in the status bar.

/who
    List online users in the status bar.

/history
    Fetch older message history.

MENU
Press Esc to open the menu (when no image preview is open). Use ↑/↓ to navigate and Enter to select.

Cycle theme
    Step through available colour themes: Dracula, Nord, Gruvbox, Solarized Dark, Tokyo Night, Monokai.

Toggle notifications
    Enable or disable desktop notifications and terminal bell.

Image Preview
    Toggle inline image preview (persisted to config).

Open URLs with
    Cycle through available URL openers: xdg-open, browsh, w3m. Only openers found on PATH are offered. The choice is persisted to config.

Pick color
    Set your username colour (loaded from server).

Logout
    Clear saved token and exit.

Quit
    Exit without clearing token.

CONFIGURATION
Settings are persisted to ~/.skychat_tui.json.

username
    Pre-fills the login screen.

token
    Saved auth token for resuming sessions without re-entering credentials.

theme
    Active colour theme. Default: Dracula.

notifications
    Whether desktop notifications are enabled. Default: true.

image_preview
    Whether inline image preview is enabled. Default: true.

url_opener
    URL opener used when pressing O. One of xdg-open, browsh, or w3m. Default: xdg-open. Only openers present on PATH are selectable via the menu.

IMAGE PREVIEW
Image preview is auto-detected at startup and disabled gracefully if none of the following are available:

Kitty
    Requires Pillow and the Kitty terminal emulator. Best quality, no flicker.

Sixel
    Requires Pillow and a Sixel-capable terminal (foot, iTerm2, mlterm). Good quality, minor flicker.

libcaca
    Requires img2txt (from libcaca-utils) or the python-caca bindings. Coloured ASCII art fallback, works in any 256-colour terminal.

URL OPENERS
The URL opener used when pressing O on a link or image is configurable via the menu and persisted across sessions. Available openers are auto-detected at startup using shutil.which.

xdg-open
    Default. Opens the URL in the system-configured desktop browser. Non-blocking.

browsh
    Full graphical browser rendered in the terminal. Suspends curses while running; the TUI resumes cleanly on exit.

w3m Lightweight terminal browser. Suspends curses while running; the TUI resumes cleanly on exit.

FILES

~/.skychat_tui.json
    User configuration and saved auth token.

/tmp/skychat_crash.log
    Crash traceback written when --debug is passed.

/tmp/skychat_debug.log
    Verbose debug log written when --debug is passed.

EXAMPLES

Open the login screen:
    skychat

Log in directly:
    skychat alice hunter2

Log in with crash logging enabled:
    skychat alice hunter2 --debug

Connect to a self-hosted instance:
    SKYCHAT_URL=wss://chat.example.com/api/ws skychat

REQUIREMENTS
Python 3.10 or later. The websockets package (installed automatically via pip). A terminal with 256-colour support.

BUGS
Sixel image preview may flicker on large images due to the nature of the Sixel protocol interacting with curses repaints. Use Kitty protocol for flicker-free image display.

SEE ALSO
w3m(1), browsh(1), curl(1), python3(1)

SkyChat web client: https://skych.at

LICENSE
WTFPL — Do What the Fuck You Want to Public License.
See http://www.wtfpl.net/ for details.