Documentation

Print useful little things from agents, scripts, and terminals.

Slipbridge is a local-first CLI for thermal receipt printers and Brother label printers. It favors explicit command-line contracts, JSON output, durable queueing, and simple files you can inspect when something gets weird.

Quickstart

Use the source install while the release packaging is still settling. The installed binary exposes the same command surface used by the docs.

git clone https://github.com/slipbridge/slipbridge
cd slipbridge
cargo install --path . --force
slipbridge doctor --json

If you are working inside the repository, `just install-local` runs the same local install path. `slipbridge doctor --json` confirms USB access and the image pipeline.

Printer setup

Slipbridge resolves printers from explicit selectors or discovery results. The important selectors are:

ESC/POS over TCP

tcp://epson-m30.local:9100

Raw socket printers, common for receipt printers.

USB ESC/POS

usb://04b8:0e15

USB vendor and product id, with optional bus and address.

CUPS labels

cups://Brother_QL_810W

Preferred path for Brother QL label printers on macOS and Linux.

slipbridge printers list --json
slipbridge printers inspect --printer cups://Brother_QL_810W

Print files

Image printing works across the driver paths. Text, markdown, and templates are rendered to a printer-ready PNG first, then sent through the selected driver.

slipbridge print ./receipt.png --type image \
  --printer tcp://epson-m30.local:9100 --paper 80mm

slipbridge print ./note.md --type markdown \
  --printer cups://Brother_QL_810W --driver cups --media c62

Use `--json` when another process needs to read the result. That includes printer ids, resolved driver, queue state, bytes sent, and job id.

Labels and templates

Brother label workflows use CUPS plus label metadata. `--media c62` infers a 62 mm roll. `--label-length-mm 100` creates a fixed 62 x 100 mm label. `--landscape` lays content out sideways before rotating it for the printer.

slipbridge render ./note.md --type markdown \
  --output preview.png --media c62 --label-length-mm 100

slipbridge print ./badge-data.json --template ./badge.hbs \
  --printer cups://Brother_QL_810W --driver cups \
  --media c62 --label-length-mm 100 --landscape

Template data

Templates use Handlebars syntax. The input file is JSON.

{
  "name": "Avery",
  "subtitle": "My bot calls me"
}

# {{name}}

{{subtitle}}

Queueing

Printing is serialized per printer. A job is written to disk before it is sent, then a worker claims queued jobs and holds a printer lock while bytes are in flight.

slipbridge print ./badge.png \
  --printer cups://Brother_QL_810W --enqueue --json

slipbridge jobs list --json
slipbridge jobs run --once --json

Queue state lives in the platform data directory by default. Set `SLIPBRIDGE_STATE_DIR` when testing isolated queues.

Printer defaults

Defaults keep repeated commands short. They are stored locally in `printers.toml`, so agents can inspect or update the same settings a human uses.

slipbridge printers defaults set \
  --printer cups://Brother_QL_810W \
  --driver cups --media c62 --cut-mode end-of-page

slipbridge printers defaults show \
  --printer cups://Brother_QL_810W --json

CLI reference

`print`

Render and send an input file. Add `--enqueue` to return immediately with a job id.

`render`

Render text, markdown, templates, or images to PNG without printing.

`printers list`

Discover USB, TCP, Bonjour, and CUPS destinations.

`printers inspect`

Resolve driver candidates and capability flags for a selected printer.

`jobs run`

Run the queue worker once or as a polling loop.

`doctor`

Check local USB access and image rendering.

Troubleshooting

Printer discovery finds office printers

Use an explicit `cups://`, `tcp://`, or `usb://` selector. CUPS destinations that discard output are rejected before printing.

Brother labels are clipped

Set `--media c62`, add `--label-length-mm`, and use `slipbridge render` to inspect the PNG before sending it to the printer.

Agent scripts need stable parsing

Pass `--json` and key off `ok`, `printer.id`, `driver.resolved`, `job.id`, and `job.state` rather than human output.

Hosting this site

This website is plain static HTML, CSS, and JavaScript. Cloudflare Workers serves the static assets from the `site` directory defined in `wrangler.jsonc`. No build command is required for automatic deploys.

Build command:   none
Deploy command:  npx wrangler deploy