░▒▓█ The guide

BadTerm help

Everything BadTerm does, and how to get at it. Inside BadTerm, Alt-Z shows every key on one screen. On a Mac, every Alt key below is Cmd.

01Getting started

Install BadTerm from the downloads, or with cargo install badterm, and start it. After a moment's splash screen it waits, not connected.

1. Press Alt-D for the dialing directory. The Vortex BBS, BadTerm's home board, is already in it.
2. Choose a BBS with the arrow keys and press Enter to call it.
3. To call one that isn't in the directory, press Q (quick connect) and type its address: bbs.example.org, bbs.example.org:2323, ssh://[email protected].
4. Alt-H hangs up; Alt-X leaves BadTerm.

BadTerm also answers telnet:// links in your browser (the Windows installer and the macOS app set that up), and takes an address on its command line: badterm bbs.example.org.

Looking for boards to call? The Telnet BBS Guide lists hundreds, and its list imports straight into the directory.

02Keys

03The dialing directory

Each entry keeps how to reach a BBS and how to show it. In the entry form, Tab and the arrow keys move between fields, and Space or ← → change the ones with choices:

Address, Port, Protocol

Telnet, Telnet over TLS ("TelnetS", port 992), SSH, RLogin, raw TCP, or Modem, where the address is a phone number (see modems). The address may carry the port: host:2323.

Emulation

CP437 (ANSI-BBS, the usual), UTF-8, Avatar, RIPscrip, PETSCII (Commodore 64), C128 (its 80 columns), ATASCII (Atari), Viewdata (Prestel), Mode 7 (BBC Micro), IGS (Atari ST) or SkyPix (Amiga). See emulations.

Screen mode, Font

40x25, 80x25 to 80x60 (80x28 in the VGA's 8x14 font) and 132 columns; your own .fnt or .psf fonts, from the fonts folder (badterm --paths); the Amiga fonts for Amiga boards; and code pages (CP866, KOI8-R, CP1251, Greek, Hebrew, Turkish, Baltic, Central and West European, ...) for boards in other languages. A BBS can also choose them itself. With one on the screen, what you type and paste goes in its code page, and copying gives the characters it shows.

iCE colors

Auto leaves it to the BBS; On shows bright backgrounds; Off blinks.

Phosphor mode, Bell

This BBS's own CRT look and bell, or the defaults from Settings.

Baud rate

Show what arrives at a modem's speed, so ANSI animations play as they were drawn.

User name, Password, Auto-login

See logging in.

Group

A group to list it in, such as "Art" or "Retro". G in the list shows one group at a time, then the next, then all again.

Status line

Off leaves the BBS's screen alone in the window, with no status bar under it.

Capture, Capture file

Record every call to this BBS; see capturing.

Downloads, Uploads

This BBS's own folders for files it sends and for choosing files to send it; empty for the folders in Settings.

Script

A script to run once the call connects; see scripts.

On a field that holds a file or a folder (Script, SSH key file, Capture file, Downloads, Uploads), F2 or Ctrl-O browses for one: Enter opens a folder or chooses, Backspace goes up, F7 makes a folder, and Tab types a path instead.

I imports a directory from SyncTERM (.lst), NetRunner (.phn), Qodem (fonebook.txt), EtherTerm (.xml), MagiTerm (magiterm.ini), CSV (including the Telnet BBS Guide's list), JSON or TOML: pick the file from its folder. You can also drop the file on BadTerm's window. X exports one: choose the folder and the name; the name's extension picks the format.

A BBS that answers busy, or doesn't answer, is called again every 15 seconds, up to ten times. Alt-R calls at once; Esc stops.

04Several calls at once

Up to nine calls can be open at once, each in a tab of its own. Alt-N opens the dialing directory to call a BBS in a new tab; dialing from Alt-D during a call asks whether to do that (T) or to hang up and dial in its place (Y). Alt-T shows the next call, Shift-Alt-T the one before, and Alt-H hangs up the call on screen and closes its tab.

With more than one call open, the status bar starts with a number for each, the one on screen highlighted; click one to show it. Calls off screen carry on: they receive, run their scripts and macros, redial, and finish their transfers. A * by a number means that call has sent something new, and a ! that it wants you: it rang the bell, asked for a login or an upload, finished a transfer, or hung up (the status bar says which). Only the call on screen plays music, though a bell off screen still beeps. Each call keeps its own place in the scrollback, and Alt-X asks before hanging them all up.

05Logging in

With Auto-login on, BadTerm answers a BBS's login and password questions with the entry's user name and password. Alt-L sends them by hand: the name the first time, the password the next. Passwords are kept in your system's keychain (Keychain on macOS, Credential Manager on Windows, the Secret Service on Linux); where there is none, they stay in the directory file.

RLogin logs straight in with the user name and password. SSH tries, in order: no password (for BBSes that run their own login), the key file set in the entry, your SSH agent, your ~/.ssh keys, then a password or code. Anything it needs and doesn't have, it asks for, and offers to remember a password. The first time you call an SSH or TLS BBS, BadTerm remembers its key; if the key ever changes, BadTerm refuses to connect and says why.

06File transfers

• ZMODEM downloads start by themselves when the BBS sends a file. If one is interrupted, it is kept as name.part and picks up where it stopped the next time the BBS sends that file.
• Kermit downloads start by themselves too.
• For YMODEM, YMODEM-G and XMODEM, start the BBS's side first, then press Alt-G and choose the protocol. XMODEM asks what to call the file.
• To upload, press Alt-U (or drop files on the window), pick the files (Space marks several), and choose the protocol with ← →. Start the BBS's receive first, except with ZMODEM, which BadTerm notices by itself.

Downloads go to Downloads/BadTerm; Settings, Folders, changes that. A download never replaces a file that's already there. Esc cancels a transfer.

07Emulations and systems

CP437

ANSI-BBS in the IBM PC character set: what almost every BBS sends.

UTF-8

For systems that send Unicode. Alt-E switches between the two during a call.

Avatar

AVT/0 and AVT/0+, the compact codes of Opus, Maximus and other FidoNet-era BBSes, alongside ANSI.

RIPscrip

The graphics of RIPterm-era BBSes: scenes of lines, shapes and fills on a 640x350 screen, with the text screen (80x43) over them. Click a button or a mouse area to send its command. BadTerm tells the BBS it understands RIP when asked, so the BBS sends its graphics. Icons and scene files the BBS saves or asks for are kept in its folder of the file cache, and also looked for in your downloads; the BBS can send them itself, and scenes show as they arrive. Buttons and the BBS's questions can use text variables such as $DATE$, and a BBS can ask you for one of its own (your name, say), which it may keep for next time.

Sixel

Pictures the BBS sends as sixel graphics, in any emulation but PETSCII and ATASCII: drawn at the cursor, up to 256 colors, scrolling with the text and kept in the scrollback. Nothing to set: BadTerm tells a BBS that asks that it can show them.

SyncTERM pictures

Synchronet's graphical doors (SyncDoom and the like) draw PPM and JPEG XL pictures with SyncTERM's commands, and BadTerm draws them too. A BBS can keep files for them in a cache on your computer: a folder per BBS in BadTerm's cache folder, at most 256 MB each, which you can delete at any time.

The mouse

A BBS or door that asks for the mouse (Synchronet's games do) gets your clicks, drags and wheel. Hold Shift to select and copy text instead.

Fonts from the BBS

Fonts a BBS sends (CTerm's loadable fonts) are used where it asks for them.

SyncTERM sound

Those doors' sound effects and music: WAV, AIFF, VOC, FLAC, MP3, Ogg Opus and Vorbis sounds and synthesized tones, on 16 channels mixed together. Alt-M turns sound off.

PETSCII

Commodore 64 BBSes, on a 40x25 screen in the C64's colors and character sets. The C64's F1 to F8 are on your F1 to F8, and RUN/STOP is Esc. Auto-login answers C64 boards' prompts, and copied text comes out as the characters on the screen.

C128

The Commodore 128's 80-column screen: the same PETSCII on 80x25, in the colors of its RGBI monitor.

ATASCII

Atari 8-bit BBSes, on a 40x24 screen in light blue on blue.

Viewdata

Prestel-style viewdata services such as Telstar: the 40x24 teletext page with its block graphics, double height and eight colors. Enter is the # key that ends what you type; * is *. Alt-K reveals concealed text, such as a quiz's answers.

Mode 7

BBC Micro BBSes, on the BBC's teletext screen: 40x25, scrolling, with the BBC's own characters and keys (Delete is DEL).

IGS

Atari ST BBSes with Instant Graphics and Sound: their VT-52 text and drawings (lines, shapes, fill patterns, text in many sizes) on the ST's screen, and menus you click, with their sound: the built-in effects, chip music and the sound chip's own data, on an emulated sound chip (MIDI notes as plain tones). Alt-M turns it off.

SkyPix

Amiga BBSes (C-Net and SkyLine) with SkyPix: ANSI text in the Amiga's Topaz font with drawings over it, in the Amiga's 16 colors, with the brushes and sound samples the BBS sends. A click is sent to the BBS, as SkyPix menus expect. Its Amiga fonts are drawn from your own copies: put a font's name.font and name/ folder in the fonts folder (badterm --paths).

Amiga boards look right in an Amiga font (Topaz, MicroKnight, P0T-NOoDLE, mO'sOul), chosen in the entry, or by the BBS itself.

08Dialing with a modem

BadTerm can dial out through a real modem on a serial port, a USB modem, a WiFi modem, or a program that acts like one (such as tcpser).

1. In Settings (Alt-O), on the Modem tab, set the serial port (type it with Enter, or step through the ports BadTerm finds with ← →): /dev/ttyUSB0 on Linux, /dev/cu.usbmodem… on a Mac, COM3 on Windows.
2. Set the speed (between the computer and the modem: 115200 suits most), flow control (RTS/CTS for almost every modem), the init string (ATZ, or AT&F for the factory settings) and the dial command (ATDT for tone, ATDP for pulse).
3. Add a directory entry with the protocol Modem and the phone number as its address.

When you call it, you see the modem's replies as it dials. BUSY and NO ANSWER are redialed like a busy BBS; the call ends when the carrier drops (NO CARRIER). Alt-H hangs up.

09The look

• Phosphor mode (Alt-P) draws a CRT: glowing text, scanlines and curved glass, in color or as a green or amber monitor. Settings, Display, sets how much the text glows, how strong the scanlines are and how curved the glass is, each from off to strong.
• Alt-W switches between 8- and 9-dot characters (a VGA's 9th column joins up the line drawing). Alt-A picks the shape: square pixels, or 4:3 as on a CRT, or 16:10 or 16:9.
• Settings, Scaling: fit, the default, keeps the picture's shape, and the window settles into that shape when you resize it, so there are no borders; or whole-number steps for exact pixels, or stretch to fill. Alt-Enter is full screen. BadTerm opens at the size and place you left it.
• Settings, Monitor bezel: draw a monitor around the screen. There are four built in; more are in the extras, and you can use a photo of your own (a PNG whose screen is see-through), put in the bezels folder.
• Settings, Colors: fourteen color schemes for BadTerm's own screens (BadTerm, the default, is in its logo's colors), or color each part yourself. More are in the extras. "Import a theme" brings one in; "Save as a theme" writes yours to a file to share.
• Settings, General, Bell: beep, flash the screen, both, or nothing. A directory entry can have its own.

10Capturing and saving

• Alt-C starts and stops capturing everything the BBS sends to an .ans file, to view later in any ANSI viewer, or in BadTerm with Alt-F.
• An entry's Capture setting records each call to that BBS from the start. Its Capture file names the file: {name}, {date} and {time} are filled in, and a name ending in .txt keeps only the text, as a log.
• Alt-S saves the scrollback as .ans or .txt, or the screen as .png: choose the folder, and the name (Tab moves between them).
• Alt-F views ANSI art files with their SAUCE title, artist and group (I shows them).

11Keyboard macros

Settings, General, Keyboard macros, sets what Alt-1 to Alt-0 send, written as in Telix and QModem: ^M is Enter, ^[ Esc, ^A to ^Z the other control keys, ~ waits half a second, and {user} and {password} are the directory entry's. {user}^M~{password}^M, for example, logs in. An entry can have its own: M on it in the directory sets them, and where one is empty, the one in Settings is sent.

12Scripts

A script logs in or finds its way around a BBS, as Telix's SALT did. Scripts are written in Rhai and kept in the scripts folder (badterm --paths shows where). Name one as an entry's Script to run it once the call connects, or press Alt-J during a call to choose one (Alt-J again stops it). A script sees what the BBS sends as plain text:

if wait("Login:", 20) {           // seconds; false if it never came
    send(user() + "\r");
    wait("Password:");            // 30 seconds when no time is given
    send(password() + "\r");
}
let which = wait_any(["[Y/n]", "Main Menu"], 30);   // which came, or -1
if which == 0 { send("n"); }
sleep(0.5);
notify("Logged in to " + bbs());

screen() is the text on the screen, and hangup() ends the call. The project's login.rhai logs in to most boards.

13Moving the hotkeys

Settings, General, Hotkeys, lists what each Alt key (Cmd on a Mac) does. Choose one, press Enter, then the letter you want for it; an action that had that letter takes the old one. Del puts a key back where it usually is. The status line and help show the keys as you set them. On the same tab, New entries' font and New entries' screen are what an entry you add starts with.

14Where things are kept

badterm --paths prints every location. Your directory, settings, themes and bezels are in:

Linux

~/.config/badterm (captures in ~/.local/share/badterm)

macOS

~/Library/Application Support/dev.Bad-Cluster.BadTerm

Windows

%APPDATA%\Bad Cluster\BadTerm\config

The directory is dialer.toml and the settings settings.toml, plain text you can edit or back up. Themes go in the themes folder and bezels in bezels. Files BBSes keep on your computer (SyncTERM's cache) are in BadTerm's cache folder, a folder for each BBS; badterm --paths shows where.

15The command line

badterm                          start, not connected
badterm bbs.example.org          call a BBS (host:port, telnet://,
                                 ssh://user@host:port, raw://)
badterm art.ans                  view ANSI art
badterm --import syncterm.lst    add entries to the directory
badterm --export bbses.csv       write the directory out
badterm --paths                  show where things are kept
badterm --render art.ans out.png draw ANSI art to an image
        [--screen] [--crt color|green|amber] [--glow G] [--scanlines S]
        [--curvature C] [--nine-dot] [--aspect] [--font NAME]
        [--bezel NAME]

On Windows, BadTerm is a windowed program, so to see its output run it from PowerShell, or with start /wait badterm --help in Command Prompt.

16When something's wrong

The BBS looks garbled

It may speak another emulation: try UTF-8 (Alt-E), or set the entry's emulation to the one the BBS's listing gives: Avatar, RIPscrip, PETSCII, ATASCII, Viewdata, Mode 7, IGS or SkyPix.

Blinking text where colors should be

Press Alt-I for iCE colors, or set iCE colors to On in the entry.

Passwords aren't remembered on Linux

BadTerm uses the Secret Service (GNOME Keyring or KWallet). Without one, passwords stay in dialer.toml.

The modem doesn't answer

Check the serial port and speed in Settings, Modem; try flow control "none" for a cable without RTS/CTS; and make sure nothing else has the port open.

A BBS's mouse menus don't respond

Make sure Shift isn't held: with it, the mouse selects text instead of going to the BBS.

Something else

Call The Vortex BBS and ask, or report a problem.