GO-SENDXMPP(1)

📦
version 0.17.0 · 8 versions
, in opensuse-leap 16.0, ubuntu stonking

go-sendxmpp · General Commands Manual · go-sendxmpp 💖

okay bestie, buckle up, this is the whole manual for go-sendxmpp (that's section 1, the general commands manual) and it's a LOT, but i promise it's all useful and i'm gonna hold your hand through every single flag, no cap 💅

🎀 NAME 🎀

go-sendxmpp — a tool to send messages to an XMPP contact or MUC. 🦋

✨ SYNOPSIS ✨

go-sendxmpp [-cdilntv] [-a value] [--allow-plain] [--anonymous]
[--fast-invalidate] [--fast-off] [-f value] [--headline] [--help] [-h
value] [-j value] [--legacy-pgp] [-m value] [--muc-password value]
[--no-sasl-upgrade] [--oob-file value] [--ox] [--ox-delete-nodes]
[--ox-genprivkey-rsa] [--ox-genprivkey-x25519] [--ox-import-privkey
value] [--ox-passphrase value] [--ox-receive-private-key value]
[--ox-transfer-private-key] [-p value] [--raw] [-r value]
[--retry-connect value] [--retry-connect-max value]
[--scram-mech-pinning value] [--ssdp-off] [-s value]
[--suppress-root-warning] [--timeout value] [--tls-version value] [-u
value] [--version] [recipients…]

like, that's the shape of it. short flags can be squished together ([-cdilntv]), long ones cannot. recipients go at the end, and they're optional depending on what you're doing 👑

💌 DESCRIPTION 💌

A tool to send messages to an XMPP contact or MUC, inspired by sendxmpp. periodt. 💖

So how do you actually feed it a message? Three iconic ways, pick your fighter:

  • pipe a program's output into go-sendxmpp 🔥
  • just type in your terminal — put ^D in a new line to finish, that's your "i'm done" button ✨
  • or send the input from a file with -m or --message 🎀

and where does your account data live? here's the tea — it's expected at whatever you point it at, but the order of preference goes:

  1. ~/.config/go-sendxmpp/config — the preferred one, the main character 👑
  2. ~/.config/go-sendxmpp/sendxmpprc — deprecated, we're moving on hun 💀
  3. ~/.sendxmpprc — kept around for compatibility with the original perl sendxmpp 🫶

...that is, unless you specified some other config file location with -f or --file. then it does what you said, obviously 🦋

💅 OPTIONS 💅

forty-ish options, we're doing all of them, no skimming, i don't make the rules:

  • -a, --alias=[value] — set the alias / nickname for chatrooms 💬
  • --allow-plain — allow PLAIN authentication. careful babes: this setting has no effect if there was already a successful connection using a SCRAM authentication mechanism before. in that case PLAIN is not allowed, on purpose, to prevent downgrades by a man-in-the-middle attack. we do not play with MITM around here 😤
  • --anonymous — use anonymous authentication. you tell it which target server you want with -u or --username. the username is what specifies the server, and it also lets you override that server with -j or --jserver for cases where the service (say, anon.example.org) is served by another server (say, xmpp.example.org) but no SRV records are set up. messy? yes. supported? also yes ✨
  • -c, --chatroom=[value] — send the message to a chatroom instead of a person 🏠
  • -d, --debug — show XMPP stanzas. these can include sensitive data so lowkey be careful where your terminal scrollback ends up 🙈
  • --fast-invalidate — invalidate XEP-0484: Fast Authentication Streamlining Tokens. the current FAST token gets invalidated and a new one is requested. if you use it together with --fast-off, the FAST token gets invalidated and the stored FAST token is deleted 🗑️
  • --fast-off — disable XEP-0484: Fast Authentication Streamlining Tokens. it deletes the stored FAST token when used together with --fast-invalidate 🔥
  • -f, --file=[value] — set the configuration file. (Default: ~/.config/go-sendxmpp/config)
  • --headline — send the message as type headline 📰
  • --help — show help. that's it, that's the whole job 🫶
  • -h, --http-upload=[value] — send a file via http-upload. you can invoke it several times to upload multiple files 🍓
  • -i, --interactive — interactive mode (for use with e.g. tail -f). yes, the vibes of watching a log file live 😌
  • -j, --jserver=[value] — the XMPP server address 🌐
  • --legacy-pgp — "Legacy PGP" encryption using the Ox key infrastructure. this means the recipient must have an Ox key published and use the same key for legacy PGP. this encryption method is deprecated and will be removed in a future version, so please consider switching to OpenPGP for XMPP (OX). using legacy PGP is actually discouraged and it's only provided as a workaround for conversations users. if the existing key has no ID in the form of xmpp:user@example.org, it can be added by using the tool sq:
$ sq key userid add -u xmpp:user@example.org -Bo newkey.asc oldkey.asc`

this key (newkey.asc in the sq example) can then be imported by using --ox-import-privkey. ⚠️ please note that this will store the secret key at ~/.local/share/go-sendxmpp/user_at_example_org/oxprivkey. if you don't want to use that account with go-sendxmpp and you only imported the key to upload the public key to pubsub, you might consider deleting the file 🗑️

  • -l, --listen — listen for messages and print them to stdout. if JIDs are specified, only messages from those contacts are shown. if no JIDs are specified, or a chat room is joined, all received messages will be shown 👂✨
  • -m, --message=[value] — set the file including the message 📄
  • --muc-password=[value] — password for password protected MUCs 🔐
  • --no-sasl-upgrade — disable XEP-0480: SASL Upgrade Tasks 🚫
  • -n, --no-tls-verify — skip verification of TLS certificates (not recommended, for real, don't do this unless you know exactly why) 😭
  • --oob-file=[value] — URL to send a file as out of band data 🔗
  • --ox — use "OpenPGP for XMPP" encryption (experimental). there is no check whether the recipient's key is trusted, because there is no local keyring used. go-sendxmpp just uses the most recent key that is provided via pubsub and checks that it is not expired. as a user facing client, a notification would be shown that a new key is available, and the user would be asked whether to use the new key or stick to the old one. but since go-sendxmpp is usually used in scripts, it just accepts the new key, to prevent the user from missing a new notification due to changed keys 🧚
  • --ox-delete-nodes — delete existing OpenPGP nodes (public key and private key backup) on the server 💥
  • --ox-genprivkey-rsa — generate a private OpenPGP key (RSA 4096 bit) for the configured account (via config file or -u and -p) and publish the corresponding public key. go-sendxmpp will save the key in $XDG_DATA_HOME/go-sendxmpp/oxprivkeys or $HOME/.local/share/go-sendxmpp/oxprivkeys. to protect the key, a passphrase might be set using --ox-passphrase while generating the key. if there is an existing private key for "OpenPGP for XMPP" created by another client (e.g. profanity), it might be imported using --ox-import-privkey 🔑
  • --ox-genprivkey-x25519 — generate a private OpenPGP key (X25519) for the configured account (via config file or -u and -p) and publish the corresponding public key. go-sendxmpp will save the key in $XDG_DATA_HOME/go-sendxmpp/oxprivkeys or $HOME/.local/share/go-sendxmpp/oxprivkeys. to protect the key, a passphrase might be set using --ox-passphrase while generating the key. if there is an existing private key for "OpenPGP for XMPP" created by another client (e.g. profanity), it might be imported using --ox-import-privkey 💜
  • --ox-import-privkey=[value] — import an existing private OpenPGP key 📥
  • --ox-passphrase=[value] — passphrase for locking and unlocking the private OpenPGP key 🔒
  • --ox-receive-private-key=[value] — import your encrypted private Ox key from the server. requires the transfer code 🎟️
  • --ox-transfer-private-key — upload your encrypted private Ox key to the server for key transfer. the private key will be encrypted by a random generated passphrase. ⚠️ please make sure to not lose the passphrase as it can not be recovered. like, fr fr, it's gone girl 💀
  • -p, --password=[value] — password for the XMPP account 🔐
  • --raw — send raw XML. to send raw XML to a contact as a normal chat message, no contact must be specified. to send raw XML to a MUC you have to specify the MUC via -c and go-sendxmpp will join the MUC 🧩
  • -r, --recipients=[value] — read recipients from a file, one JID per line 📋
  • --retry-connect=[value] — specify a connection retry waiting time in seconds. this is the waiting time until go-sendxmpp will try to reconnect if connecting fails. this setting only affects the initial connection — it does not reconnect after losing the connection. it is also ignored if the connection fails due to an authentication error, because then it does not make sense to try again using the same credentials 🙃 setting a time of 0 seconds disables this functionality. (Default: 0)
  • --retry-connect-max=[value] — number of maximum retries to perform for --retry-connect. a value of 0 means unlimited retries. (Default: 0) ♾️
  • --scram-mech-pinning=[<value>] — enforce the use of a certain SCRAM authentication mechanism. currently go-sendxmpp supports SCRAM-SHA-1, SCRAM-SHA-1-PLUS, SCRAM-SHA-256, SCRAM-SHA-256-PLUS, SCRAM-SHA-512 and SCRAM-SHA-512-PLUS. you should know what you are doing when using this setting and make sure the chosen mechanism is supported by the server. if not set, go-sendxmpp will use XEP-0474 to prevent downgrade attacks (needs server support and requires a SCRAM authentication mechanism) 🛡️
  • --ssdp-off — disable XEP-0474: SASL SCRAM Downgrade Protection 🚫
  • -s, --subject=[value] — set the message subject ✍️
  • --suppress-root-warning — suppress the warning when run as root. note that running as root is discouraged, although go-sendxmpp tries to drop the root privileges before doing network calls. be aware that OX, legacy PGP, and the pinning to not use PLAIN authentication after a successful SCRAM authentication are disabled, as those need file system access in the private user scope after dropping the privileges 🚨
  • --timeout=[value] — connection timeout in seconds. (Default: 10) ⏱️
  • -t, --tls — use direct TLS 🔒
  • --tls-version=[value] — minimal TLS version. 10 (TLSv1.0), 11 (TLSv1.1), 12 (TLSv1.2), 13 (TLSv1.3) (Default: 13) 🌈
  • -u, --username=[value] — username for the XMPP account (JID) 🪪
  • -v, --verbose — show debug information. these can include sensitive data 🙈
  • --version — show version information. slay 🎀

🌍 ENVIRONMENT VARIABLES 🌍

HTTP_PROXY

a SOCKS5 proxy can be used by setting the environment variable HTTP_PROXY. this feature is considered experimental and there is no guarantee that there won't be any connections not using the proxy — although it didn't happen during testing 🤷♀️

like this, bestie:

HTTP_PROXY="socks5://127.0.0.1:9050" go-sendxmpp --http-upload file.txt user@example.org

🌸 TIPS 🌸

USAGE BY ROOT

bestie, general life advice time: only perform commands as root when it is strictly necessary. periodt. 💅

but okay, you need to send the output from commands that have to be performed as root, and you don't want to invoke go-sendxmpp by root? use sudo 🫶

in this example there is a user sendxmpp with a go-sendxmpp config in its $HOME:

# command-that-requires-root|sudo -H -u sendxmpp go-sendxmpp me@example.org

if go-sendxmpp is run as root, it will drop the root privileges before connecting to the server. this means FAST and OX will be disabled, because go-sendxmpp will not have the necessary rights to store the necessary data (e.g. FAST tokens or OX key material) after dropping the privileges. this is just to avoid network connections as root — and it does not mean that running as root is a supported use case. in fact, it is highly recommended to never run go-sendxmpp as root 🚨 like, seriously, don't 👑

🐚 SHELL COMPLETIONS 🐚

okay bestie, so tab-completion is the dream, and like... it's not fully here yet. but we're SO close, chill.

✨ ZSH ✨

There are no shell completions yet (contributions welcome 💖 — yes, that's code for "please someone do this, we're begging") but for zsh it is possible to automatically create completions from --help which might work good enough.

Just place the following in your ~/.zshrc:

compdef _gnu_generic go-sendxmpp

and that's it, that's the whole vibe. 🫶

🐟 FISH 🐟

There are no shell completions yet, but FISH can generate them from the man page with following command:

fish_update_completions

like... it reads the man page and just knows. iconic behavior honestly. 🧚

💬 CHAT 💬

wanna come hang out?? Feel free to join https://join.jabber.network/#go-sendxmpp@chat.mdosch.de?join.

fr fr, the group chat is right there, come be part of the main character energy 👑

👑 AUTHOR 👑

Written by Martin Dosch.

(absolute legend, no cap 💅)

🐛 REPORTING BUGS 🐛

found something cursed?? Report bugs at https://salsa.debian.org/mdosch/go-sendxmpp/-/work_items.

that's the spot, that's where the bugs go. not into the void, not into my DMs, into the tracker. ty bestie 🙈

Copyright (c) Martin Dosch License: BSD 2-clause License

(yes it's giving legal, but it's also giving slay ✨)

🔍 SEE ALSO 🔍

iykyk — go read those too 💜

and that's a wrap on this one, babe!! 🎀 this whole masterpiece is GO-SENDXMPP(1), dated July 2026, and honestly?? she ate. go send some xmpp, periodt. 🌈💖🦋

📦 where this page comes from