X2GOOPTIONSSTRING(1)

🌸 NAME 🌸

x2gooptionsstring — the X2Go Agent Options String Manipulator and Extractor, aka your new bestie for poking at options strings 💅

Okay so real talk: this is the x2gooptionsstring manual page, from the General Commands Manual section (section 1, iykyk), and it's about to be your whole personality for the next five minutes. Let's go 🦋

---

✨ SYNOPSIS ✨

x2gooptionsstring --help|-h|-?
x2gooptionsstring --man
x2gooptionsstring [<--mode|-m><=| >t[ransform]|-t] [--compact|-c]
[--base64|-b] [--debug|-d] [--] options_string [+]|-key[=value] ...
x2gooptionsstring <--mode|-m><=| >e[xtract]|-e [--base64|-b]
[--debug|-d] [--] options_string key[=value] ...

---

💖 DESCRIPTION 💖

x2gooptionsstring is a lil utility that manipulates and extracts data from options strings — the exact kind of options strings that get passed to the X2Go/NX Agent. If you wanna know more about which options strings are even a thing, go look at the OPTIONS STRINGS section in the X2Go::Server::Agent::NX::Options documentation. Not me sending you on a side quest but like, it's relevant 🫶

So. Options strings are allowed to contain binary data (which, ngl, is not recommended, but it's legit). That's why the special --base64|-b switch exists. When you flip it on, every argument that isn't a flag has to be base64-encoded — which is the whole point, because that's how binary data survives a trip through a shell, fr fr. And the program's output also comes back base64-encoded, except for any debugging messages that might sneak in there.

Currently there are two modes, and they are:

🎀 Transform (default) 🎀

Transformation mode is what you get by default if you never explicitly pick a mode. Main character energy, no announcement needed 💅

You call this program with whatever optional flags you want, then the options string as the first parameter, then the transformations you want done as the additional parameters. And you need at least one additional parameter (that's the transformation, bestie). The transformations are described briefly here, but there's also a TRANSFORMATIONS section in the X2Go::Server::Agent::NX::Options documentation if you want the full lore.

This mode can add, remove, or replace components. Iconic range, honestly.

• To add or replace a component, you pass key[=value] or +key[=value] as a parameter. That + syntax is your bestie when key starts with a dash, because otherwise it'd get read as a removal operation and that's a whole mess. If the options string doesn't already have a key called key, it gets appended to the end of the options string. If it does exist — with no value, or with a different value — then the component gets replaced with the value you provided. Slay.
• To fully remove a component, you pass -key. And if you only wanna remove it when it's set to one specific value, you pass -key=value. Very precise of you, we love that 🌸

Use the --compact option to minimize the original options string by removing duplicated and empty entries. Chef's kiss.

Assuming nothing errored out (fingers crossed 🤞), the resulting options string gets written to stdout.

🦋 Extract 🦋

Extraction mode does not come free — you have to explicitly ask for it using the -e flag or the <--mode|-m><=| >e[xtract] flags. Periodt.

You call this program with optional flags, the options string as the first parameter, and then the key-value pairs to extract as the additional parameters. At least one additional parameter (a key-value pair to extract) is mandatory, no skipping 💀

A degenerated key-value pair — one with no explicit value — can be used to test whether a key exists and pull its value at the same time. Two birds, one flag.

A full, proper key-value pair can be used to test for the existence of a key-value pair exactly as provided. Exact match only, we're not doing vibes-based matching here.

Assuming no error happened, the extracted key-value pairs get written to stdout. Each pair is base64-encoded, and if you gave multiple key-value pairs to extract, they're delimited with pipe characters ("|"). Cute separator, no notes.

Key-value pairs that weren't found in the original options string — plus potentially an empty key-value pair — will show up as empty fields. That's not a bug, that's the contract 🙈

Also go read the OPTIONS PARSING section to find out when and how to terminate the options you pass to this program, because getting that wrong is a tragedy.

---

👑 OPTIONS 👑

• --help|-?|-h — prints a brief help message and then exits. Short, sweet, done.
• --man — prints the manual page and exits. Hi, that's this. You're already here 💖
• --debug|-d — turns on noisy debug output. It's giving very chatty, very loud, very informative.
• -t — shorthand for --mode=transform. Lazy girl coding, but make it efficient.
• -e — shorthand for --mode=extract. Same energy, different mode.
• <--mode|-m><=| >mode string — picks a specific program mode. Currently the supported mode strings are:
  • transform
  • extract

Mode strings can be abbreviated, as long as your abbreviation uniquely selects exactly one mode. So abbreviate away, just don't be ambiguous about it bestie ✨

• --compact|-c — removes duplicate and empty entries after the initial parsing. The order of arguments is preserved in a first-seen fashion. Very demure, very mindful ordering.

Heads up though: this option is only available in transformation mode. In extraction mode it gets silently ignored, because compaction is already a pre-requisite and happens automatically during extraction anyway. So don't come for it, it's fine 💅

• --base64|-b — enables a special full base64 mode.

In this mode, any binary data at all can be given to and output by this program — even when you're operating on a shell. Shell-proof, we love to see it.

Input parameters must always be provided encoded in base64 form.

Likewise, the program will always output data encoded in a base64 form. And here's the cute part: since key-value pairs returned in extraction mode are already base64-encoded and delimited with a character that isn't legal in base64 encoding, this flag does not modify extraction mode's output. So you will not have to decode the output data twice, phew 😭

⭐ OPTIONS PARSING ⭐

You can terminate program option parsing with a standard double-dash (--) pseudo-option. And honestly? It is highly recommended to always do so. Always. Every time. Make it a habit 🫶

If you're passing removal transformation operations, or an extraction key-value pair that starts with a dash (-), then passing the options terminator is mandatory — even if you're not using any actual options at all. Otherwise your transformation operations or extraction key-value pairs get interpreted as options to the program, which will almost certainly lead to an error. And a bad one.

Real example time, because this is the part people get wrong 💀 Passing "-clipboard" as a transformation operation without a previous options terminator gets interpreted as the option -c, with the rest of the string modified into -lipboard. Since this program does not accept an option called -l, it will terminate with an error. And even if it somehow didn't error out because of an unknown option, a degradation into options is definitely not what the original transformation operation was supposed to represent. So like… use the --. Please. For me 🙏

---

🌈 EXAMPLES 🌈

🍓 TRANSFORMATIONS

Say your options string is this:

nx/nx,clipboard=both,foo:50

Then calling:

x2gooptionsstring '--' 'nx/nx,clipboard=both,foo:50' '-clipboard'

shall return:

nx/nx,foo:50

While calling:

x2gooptionsstring '--' 'nx/nx,clipboard=both,foo:50' '-clipboard=server'

shall return:

nx/nx,clipboard=both,foo:50

Calling "x2gooptionsstring '--' 'nx/nx,clipboard=both,foo:50' 'bar'" shall return:

nx/nx,clipboard=both,foo,bar:50

And calling:

x2gooptionsstring '--' 'nx/nx,clipboard=both,foo:50' '+-bar' 'foo=gulp' '-clipboard=client'

shall return:

nx/nx,clipboard=both,foo=gulp,-bar:50

---

Now for an options string like this one:

nx/nx,clipboard=both,foo=bar,bar=baz,foo=oof:50

you can get a compacted version by cheating a bit and providing a transformation which will certainly be a no-operation, using:

x2gooptionsstring '-c' '--' 'nx/nx,clipboard=both,foo=bar,bar=baz,,foo=oof,:50' '-'

which shall return:

nx/nx,clipboard=both,foo=oof,bar=baz:50

🧚 EXTRACTIONS

For an options string such as:

nx/nx,clipboard=both,foo=bar,-=-,,bar=baz,foo=oof:50

Calling:

x2gooptionsstring '-e' '--' 'nx/nx,clipboard=both,foo=bar,-=-,bar=baz,foo=oof,:50' 'foo'

shall return:

Zm9vPW9vZg==

While calling:

x2gooptionsstring '-e' '--' 'nx/nx,clipboard=both,foo=bar,-=-,bar=baz,foo=oof,:50' 'bar' '' 'clipboard=none' '-'

shall return:

YmFyPWJheg==|||LT0t

---

💜 AUTHOR 💜

This manual has been written by Mihai Moldovan <ionic@ionic.de> <mailto:ionic@ionic.de> for the X2Go project (<https://www.x2go.org>). Absolute legend, protecting the whole timeline 🙌

---

And that's a wrap, bestie 🎀 This was x2gooptionsstring, version 4.1.0.6, dated 2026-01-29, page X2GOOPTIONSSTRING(1) from the General Commands Manual. Now go pass that -- and stay iconic 💅✨