Plugins extend tx with commands and other plugins. Install only code you trust: plugins are not sandboxed and run with the same permissions as tx. Git clones, plugin modules, dependencies, and package lifecycle scripts are trusted execution surfaces; there is no signing, provenance, permissions, rollback, catalog, or automatic-update layer.
Install the Linux x64 or arm64 standalone release with mise use -g github:fx/tx. Plugin authors who install @fx/tx from GitHub Packages for its public types must configure npm.pkg.github.com with a classic PAT that has read:packages; GitHub requires this authentication even for public npm packages. See the installation guide.
A marketplace is a Git repository containing one or more plugins, or a local directory referenced live.
tx marketplace add owner/repository
tx marketplace add https://example.com/tools.git --name tools
tx marketplace add owner/repository --full
tx marketplace add ./my-plugins
tx marketplace install
tx marketplace list
tx marketplace pin tools v1.4.0
tx marketplace unpin tools
tx marketplace remove toolslist prints one tab-separated line per marketplace: its name, its version label, its source, and the version its manifest declares — - when it declares none or its manifest cannot be read (see Declare tx compatibility). add accepts any Git clone source, optionally with the @<ref> version described in Marketplace versions. Bare owner/repository input expands to an HTTPS GitHub clone URL, and an HTTP(S) clone that fails is retried once over the SSH source derived from it, so a private repository installs from the shorthand. The installed name is derived from the source unless --name supplies one. The current repository is not auto-loaded; add it as a marketplace if you want tx to load its configuration.
Every successful marketplace add records the installed marketplace in the
marketplace property of the bundled config document,
and every successful marketplace remove removes its matching entry. The list
is ordered and can also be hand-seeded before anything is installed:
{
"marketplace": [
{ "source": "owner/repository" },
{ "source": "https://example.com/tools.git", "name": "tools" }
]
}Run tx marketplace install explicitly to install every configured marketplace
that is missing. Already-installed names are left unchanged, and one failed
entry does not stop later entries from being attempted; any such failure makes
the overall command fail after the rest have run. The command validates and
resolves the complete list before installing anything, rejecting duplicate
effective names whether names are explicit or derived. It never writes the
config list and never runs automatically.
Write-back stores a Git source without URL userinfo credentials and retains its
@<ref> suffix. A local source is stored as its fully resolved real path, so a
later invocation from another working directory cannot redirect it. If config
read or write-back fails after an add or removal succeeded, the successful
marketplace mutation stands and the config failure is reported separately.
By default, a Git-sourced add starts with a partial, sparse clone. It materializes both supported manifest locations, then the directories containing the manifest's validated plugin entries and package selections. Commit history is unchanged; the reduction applies to repository file content and the checked-out tree. If Git or the remote cannot perform the reduced retrieval, tx starts a fresh complete clone of the same source. If a declared repository path exists but the sparse tree cannot resolve it — including a symbolic link whose target was not selected — tx expands that same checkout to the complete tree and validates again before reporting a failure.
Pass --full when a plugin imports repository content outside those manifest-derived directories. It skips the reduced attempt and clones the complete Git tree immediately. This option does not change local sources: a local directory remains a live reference and Git is never run for it.
An HTTP(S) source is always tried over HTTP(S) first. If that clone fails, for any reason, tx derives the SSH source from it and clones once more under the same name. Nothing about a public marketplace changes; a private one installs from the shorthand, on the strength of the SSH key you already have.
The derived source is always git@host:path, in the SCP syntax a forge's own instructions are written in. Only the host and the path come from the HTTP(S) source: https://alice@git.company.com/team/tools.git derives git@git.company.com:team/tools.git, and https://git.company.com:8443/team/tools.git derives git@git.company.com:team/tools.git as well. A user in the source is an HTTPS credential rather than an SSH login — every forge answers SSH as git — and an HTTPS port is not an SSH port, so carrying either over would produce a source that cannot work. Percent-escapes in the path are decoded, because Git decodes them in a URL but not in SCP syntax. If you need another SSH login or a non-standard SSH port, give that SSH source yourself; tx does not guess it. Sources that are already ssh://, SCP syntax, git://, file://, or a plain path are cloned once, as they were typed.
Clone attempts run without Git's terminal prompt. Without that, a private HTTPS clone with no credential stops on the prompt and waits, and the SSH retry never happens. Credential helpers and GIT_ASKPASS are untouched, so a credential you have configured is still found and the HTTPS clone still succeeds. Only Git's own prompt is suppressed, and only while reaching a remote — cloning, and the fetch tx update performs, which needs it for a stronger reason: an update walks every marketplace you have, and one prompt would stall the run. Reading Git configuration, marketplace list, and dependency installation are unaffected.
Every clone attempt, and every fetch, runs ssh -o BatchMode=yes by default, so an unknown host key or a missing key fails rather than asking. On a clone, that default covers the first attempt as well as the SSH retry, because the first attempt can be an SSH connection too: an url.<base>.insteadOf rule rewrites an HTTP(S) source to SSH before Git dials, and ssh's own host-key and passphrase prompts go to the terminal, where turning off Git's prompt cannot reach them. On a clone that really does speak HTTP(S) the setting does nothing at all.
If you already configure an SSH command — through GIT_SSH_COMMAND, through GIT_SSH, through Git's own core.sshCommand in your global or system configuration, or as command-scope configuration supplied by the environment (GIT_CONFIG_COUNT with its GIT_CONFIG_KEY_<n> and GIT_CONFIG_VALUE_<n> entries), any of which is how a CI job usually pins a deploy key — that command is used exactly as it stands, and none of them is overridden. Yours is a deliberate invocation, an identity file, an alternate config, a proxy command, and tx has no business rewriting it. That includes its prompting behavior: a key whose passphrase is not already in your agent can still stop and ask. Which configuration files count depends on what is about to run, and the rule is the same one either way: a scope counts when Git will really apply it. A core.sshCommand set in a single repository's own configuration does not count for a clone, because git clone never applies it — the clone creates its repository rather than joining the one you are standing in — so tx would be standing down for a command Git will not run. It does count for the fetch behind tx update, which runs inside the installed checkout, where Git applies that checkout's own configuration and it outranks your global and system files: a deploy key you pinned in one marketplace's checkout is used, and is asked for first.
When both attempts fail, the failure names both sources and carries both messages, so you can see which transport failed how. The names are composed from your source with its userinfo cleared, so nothing can corrupt them, and the Git output quoted between them has every userinfo@ run taken out — the URL you gave, the URL Git echoes with the password stripped, and the host-only form Git prints when a source has a username and no password. That covers the password in every shape Git spells it. A name that appears without its @, such as a server message naming the account, is left alone: deleting a bare identifier would rewrite the text around it and report repositories you never typed. A source that leaves the user out and carries its token as the password, https://:token@host/path, is covered the same way by its :token@ run; an empty part of the userinfo is never removed on its own, because that would come to removing a bare @ and would take one out of every host named. A single attempt that fails is reported exactly as Git reported it.
add classifies its argument before doing anything else, without touching the network:
- An empty source is rejected, because resolving it would name whatever directory you are standing in.
- A source carrying a URL scheme or SCP-style
host:pathsyntax — a colon ahead of the first slash, as Git itself reads one — goes to Git. A directory whose own name contains such a colon stays reachable as a local source through a path, such as./host:path. - Otherwise the source is resolved against the working directory: an existing directory is a local source, an existing non-directory is an error, and a path that is genuinely absent goes to Git — which is what keeps
owner/repositoryshorthand working. Only a missing path counts as absent; an unreadable ancestor or a link cycle is reported as itself rather than handed togit clone. - Where a bare
owner/repositoryargument also names an existing directory, the directory wins. The remote stays reachable by its full URL.
A local source is recorded as a live reference to the directory, never as a copy, so every later tx invocation reads whatever is on disk right now — edit a plugin and rerun it, with no commit, push, or reinstall. The reference is recorded against the source's fully resolved real path, so moving to another directory or repointing an intermediate symbolic link afterwards cannot redirect it. Without --name, the name comes from the final component of that real path exactly as it is on disk, so a directory called tools.git installs as tools.git.
tx marketplace add ./repo used to hand the path to git clone, installing a snapshot of the repository's checked-out commit. It now records a reference instead. To keep the old behavior, add the same path as a file:// URL — classification leaves it with Git:
tx marketplace add "file://$PWD/repo"A local source is validated and has its selected dependency manifests installed exactly as a clone does, except that bun install runs in your own directory rather than in a copy — that is the point of a live reference. It runs only when the marketplace is added; dependencies you add to the source afterwards are yours to install. If validation or installation fails, no reference is published and tx neither deletes nor rolls back your directory. That guarantee covers tx's own cleanup only: install lifecycle scripts are trusted code running with tx's permissions, so what they do to the tree they run in is outside it.
marketplace list reports a reference's recorded target path as its source and live as its version, and marketplace remove removes only the reference, leaving the directory and its contents untouched. A reference whose target has been moved, deleted, or replaced stays listed and removable, and is reported through the recovery diagnostics that name its marketplace remove invocation.
Marketplaces and their plugins execute in deterministic order: installed marketplace names are sorted, entries retain their manifest order, and the host initializes roots followed by contributed children in FIFO order.
add takes a version on the source, spelled the way every package manager spells one:
tx marketplace add fx/cc@1.4.0
tx marketplace add fx/cc@release/1.4
tx marketplace add git@github.com:fx/cc.git@v1.4.0The ref is a commit-ish the remote publishes, resolved as a tag, then a branch, then a commit. A ref beginning with a digit is tried once more with a v prefix, so @1.4.0 finds the v1.4.0 tag almost every repository publishes, this project included. A ref that resolves nowhere fails the addition and installs nothing. The version never reaches the name: fx/cc@1.4.0 installs as cc.
The separator is the last @ outside the source's authority — the part Git reads to find the host — so an SSH login and an HTTP(S) credential are never read as one: git@github.com:fx/cc.git and https://token@example.com/fx/cc.git are unpinned sources. That is also what lets a ref contain /. A ref whose own name contains @ cannot be written as a suffix, because nothing can tell which @ you meant; give it to tx marketplace pin, where the ref is an argument of its own. Nothing is unreachable, and the failure is loud either way: the addition fails against the source it actually tried.
Classification runs first, so a version is only ever read from a source that is going to Git. A directory named tools@2 is added as a live reference under that name, and ./tools@v1.0.0 beside a ./tools directory is an error rather than a clone — a reference is live, so there is no version to pin it to.
A pin changes afterwards, and takes effect on the next update rather than moving the checkout itself:
tx marketplace pin cc v1.5.0
tx marketplace unpin ccpin fetches first and refuses a ref the remote does not publish, leaving the previous pin exactly as it was, so a mistyped ref never silently unpins anything. It records without checking anything out, because moving a checkout runs validation and a trusted dependency installation — that is tx update's job, and it carries tx update's failure handling. unpin clears the pin and the marketplace tracks its remote's default branch again.
Without a version, add installs what the remote's default branch holds — unless that commit's manifest declares a tx range the running tx does not satisfy. Then add installs the newest release from that manifest's versions history whose range the running tx does satisfy, and says so:
$ tx marketplace add example/tools
Added marketplace "tools".
Installed 1.5.0 because 2.0.0 requires tx ^2.0.0, which tx 1.8.0 does not satisfy.
A pre-release in the history is never chosen this way; pin one if you want it. The release's own commit has the last word: tx fetches that commit by its object name when the clone does not already have it, and reads the manifest it carries. A commit the remote does not serve, or whose manifest does not support the running tx after all, is not installed — and tx does not quietly fall back to an even older release in its place. When nothing qualifies, the addition fails and installs nothing, naming the running tx, the range the default branch declares, why the newest compatible release could not be used, and tx marketplace add <source>@<ref> as the way to install a particular version anyway.
No pin is recorded. The marketplace stays unpinned and is selected afresh by every tx update, so it returns to the default branch as soon as you run a tx that branch supports.
A version you name — add <source>@<ref>, a local directory, marketplace pin — is never second-guessed. When what it names does not support the running tx, the command still succeeds and warns on standard error that the marketplace's plugins will be refused, naming the range and the running version; TX_IGNORE_COMPATIBILITY=1 is how you run them anyway. A pinned commit whose manifest cannot be read is not warned about: the update that applies the pin validates it.
tx update updates everything tx has installed. tx update --dry-run reports exactly the same thing and applies nothing, and positional names limit a run to the items you name.
tx update
tx update --dry-run
tx update toolsGathering prints one tab-separated line per item — its name, its current version label, either -> <version> or up to date, and whatever detail its owner supplied — followed by one line per item that was applied. An item reporting nothing available is reported and left alone; nothing is asked to update it.
Results go to standard output and failures to standard error, so you can pipe one without losing the other. An item that reports itself as unusable is reported on standard error instead, with failed: <reason> in place of what it would have moved to, and is never applied. A name matching no gathered item is a failure too, and so is a participant that cannot report and an item whose update fails; each of those exits 1 while the rest of the run continues. Applying nothing is not a failure. A dry run exits 0 whether or not updates are available: the exit code answers "did the command work", not "is anything out of date".
tx never checks for updates on its own. No other invocation contacts a remote to learn what is available, caches a result, or prints a notice, and there is no flag or configuration key that turns such a check on.
Every installed marketplace is one item in tx update, named as it is installed. A cloned one reports the commit its checkout holds — a tag reachable from that commit where the repository publishes tags, an abbreviated hash where it does not — and what its remote's default branch now offers. A marketplace referenced from a local directory reports live and has nothing to apply: its contents are whatever the directory holds when you run tx, so nothing is fetched, moved, or modified. marketplace list reports the same label as its second column, without contacting anything.
$ tx update --dry-run
tools v1.4.0 -> v1.5.0
mine live up to date
Gathering fetches, because there is no way to learn what a remote has without asking it, and a dry run whose answer is "probably" is not worth running. The fetch writes remote-tracking refs, tags, and the objects behind them, and nothing else, so the checkout, the working tree, and the dependencies installed beside them come out of a dry run untouched. Refs follow what the remote publishes now, in both directions: a tag its publisher moved moves, and a branch or tag they withdrew goes, so a pin is always answered against what is really there rather than against a ref only your copy still has. Fetching runs non-interactively, exactly as cloning does — an update walks every marketplace you have, and one credential or host-key prompt would stall the whole run. Reading Git configuration, marketplace list, and dependency installation keep your environment as it is.
Applying moves the checkout onto the target commit, detached, then validates the marketplace and installs its selected dependency manifests exactly as adding it would — the new commit may declare different plugins or different dependencies. For a marketplace installed with reduced retrieval, tx reads that target commit's manifest before moving and adds its entry and package directories to the existing sparse checkout. A checkout installed with --full, or one already expanded by an earlier fallback, stays complete: update never turns a complete checkout sparse. If target inspection or sparse expansion is unavailable, or a repository path can only be resolved against the complete tree, tx expands the same checkout and continues once; a successful fallback remains complete for later updates. Gathering and dry runs fetch and report only — they do not change the sparse-checkout set.
A marketplace whose checkout did not move is not revalidated. If validation, installation, or final version labeling fails, the checkout is put back on the commit it held and its exact pre-update sparse-checkout state is restored. Putting the commit back discards whatever the failed preparation rewrote — an install that rewrites a committed lockfile before failing would otherwise strand the marketplace on the commit that just failed — and nothing of yours is in that set, because the update refused to start unless the checkout was clean. If an untracked file blocks the move, the commit is never forced over it; the file survives and only a sparse expansion already attempted is rolled back. What a trusted installation already wrote outside the checkout's tracked files is not put back, and tx says so rather than claiming otherwise.
A fetch that fails is reported as Git reported it, with the credential of the recorded remote taken out of the message, so a marketplace installed from a source carrying a token does not print that token when its remote goes unreachable.
A pinned marketplace targets what its pin resolves to now, rather than the remote's default branch. The pin names a ref and is re-resolved on every run, so a pin to a hash never moves, a pin to a branch moves with that branch, and a pin to a tag moves if its publisher moves the tag — tag immutability is the remote's contract, not tx's. Every run reports the pin, and reports the highest release the remote publishes above it as detail, without proposing to apply it: you pinned a version, and being moved off it unasked would defeat the pin. "Higher" means higher as a semantic version, so a tag that is not one is never reported and a pin that is not one is compared against nothing; a pre-release is never reported, though you may pin to one and hear about the first ordinary release above it.
$ tx update --dry-run
tools v1.4.0 up to date pinned to v1.4.0; the remote publishes v1.5.0
A pin may move a checkout in either direction, because you named the commit — going back to the last version that worked is most of the reason to set one. Only an unpinned marketplace is held to moving forward. A pin naming a ref the remote has stopped publishing is reported as a failed item pointing at tx marketplace pin and tx marketplace unpin, not at removing the marketplace.
Two situations stop an update, and both are reported as detail on a dry run before they refuse anything for real:
- A tracked file you edited. The edit is yours and is never discarded. Resolve it in the checkout and run the update again. Untracked files are ignored, because
bun installwrites them into every checkout — except one occupying a path the new commit tracks, which cannot be kept and moved onto: that collision is reported with the path, and the file survives. - A commit that is not an ancestor of the target. Moving anyway would silently discard the history the checkout was validated against, so an unpinned marketplace is refused — and which refusal you get says what happened. If the remote no longer has that commit anywhere, the branch was force-pushed or rebuilt, and
tx marketplace removeand add it again is the remedy. If the remote still publishes it, on a side branch or at a tag, nothing is broken: that is where a pin left the checkout, sotx marketplace pinnames it as the remedy first. A pinned marketplace is never refused for this — you named the commit.
An unpinned marketplace whose default branch declares a tx range the running tx does not satisfy is updated to the newest compatible release instead, chosen exactly as add chooses one and chosen again when the update applies, never taken on trust from what the dry run printed:
$ tx update --dry-run
tools v1.4.0 -> v1.5.0 2.0.0 requires tx ^2.0.0; 1.5.0 is the newest version supporting tx 1.8.0
That move may even go backwards, but only for an installation the running tx refuses — one whose own manifest excludes it, or cannot be read at all. That is the installation that gains from it: it moves back to the last version that loads. A marketplace whose installed commit works is never moved to an older release; it is reported as held, with nothing to apply, and the command still exits 0, because nothing is wrong:
$ tx update --dry-run
tools v1.5.0 up to date held at 1.5.0: 2.0.0 requires tx ^2.0.0
A refused installation with no usable release to move to is different: it is refused on every invocation, so it is reported as a failed item — naming the running tx, the range the default branch declares, and the three ways out: a newer tx, tx marketplace pin <name> <ref>, and TX_IGNORE_COMPATIBILITY=1 — and the run exits 1, dry run included. A pinned marketplace is never re-selected; when the commit its pin resolves to does not support the running tx, its detail says so, and nothing else changes. A default branch whose manifest cannot be read is targeted as it always was, and validating it is what reports the problem.
A marketplace whose plugins fail to load updates like any other — the participant reads storage rather than depending on a marketplace having loaded, which is what makes tx update the way out of a broken commit. A checkout tx cannot read at all is reported as one failed item naming its marketplace remove remedy, while the marketplaces around it still report and still update.
One of the items tx update gathers is tx, contributed by a bundled plugin that owns the running executable and defines no commands of its own. It compares the running version against the project's latest published release as a semantic version and offers only a strictly newer one, so a locally built executable is never dragged backwards. The lookup sends a token when GH_TOKEN or GITHUB_TOKEN is set — the first of those two that is non-empty, and no other variable is ever sent as one — which raises the rate limit; the release is public, so it works without either.
tx is composed last among the bundled plugins, so everything they own finishes updating before the binary is replaced. That ordering covers the bundled plugins only: a participant contributed by a plugin you installed through a marketplace is committed after every one of them, so it may be applied after the executable. Nothing needs it not to be — replacing the executable leaves the running process on the file it started from. How it is replaced depends on who owns the file:
- A version manager owns it. mise and npm are recognized from the executable's own resolved location, and from
MISE_DATA_DIRorMISE_INSTALLS_DIRwhen either moves mise's store off the path that would announce it. The manager is asked which tool owns that path and its own upgrade command is run for that tool —mise upgrade <tool>ornpm install --global <package>— and its output is reported. That one mise command runs withMISE_MINIMUM_RELEASE_AGE=0, so mise does not withhold a releasetxhas already offered; your configuration is untouched and every other tool keeps the policy. Afterwards the manager is asked what it has installed, and the item is reported as applied only against a version newer than the one that was running that the manager was not already reporting before the upgrade — mise lists every version it has installed, so a newer one you have pinned away from is not something this upgrade did. An upgrade that exits successfully having installed nothing is reported as nothing applied, with the manager's output and the version still installed. Nothing inside the manager's store is replaced bytx, because a manager that kept recording the old version would silently revert the update on its next install. A recognized manager that cannot be interrogated is a failure, not a reason to write into its store anyway. - Nobody owns it. The published executable and its
SHA256SUMSare downloaded, the digest is verified, and the file is staged beside the target with its executable bit set, run once to confirm it reports the published version, and moved onto the installed path in a single rename. Any mismatch aborts with the installed executable untouched, and every staged file is removed on every exit path. A locationtxcannot write to is reported by name;txnever tries to acquire privileges.
Two conditions report the release as detail and offer nothing to apply, because applying would only be refused: running from a source checkout — where the running program is the Bun runtime, not tx — and a platform with no published executable. Neither is a failure, so tx update still exits 0 while your marketplaces update normally.
The canonical manifest is .tx/config.json at the repository root:
{
"plugins": [
{ "name": "notes", "entry": "plugins/notes.ts" },
{
"name": "reports",
"entry": "plugins/reports/index.ts",
"package": "plugins/reports/package.json"
}
]
}The plugins array must be non-empty. Give every entry a unique name that is one safe path component, and use a non-empty repository-relative entry path. Entries must resolve to regular files contained by the repository, including after symbolic links are resolved. A root tx.marketplace.json remains supported for older marketplaces, but .tx/config.json takes precedence when both exist.
A plugin needs no build step or package manifest. Without package, tx looks only for package.json beside the entry's real, fully resolved file path. It does not search parent directories, so a nested entry does not inherit a marketplace-root manifest. Use the optional package field to select an exact repository-relative package.json elsewhere in the marketplace. If package is present, its value must be a string. A valid contained override may point to an absent file to skip installation; non-string, empty, absolute, escaping, non-package.json, directory, broken-link, looping-link, and externally resolving values are errors that cause marketplace addition to fail.
Before installing anything, tx validates all entries and selected package candidates. Existing manifests are resolved to regular contained files, deduplicated by real path, and installed sequentially in first plugin occurrence order with bun install running from each manifest's directory. Dependencies and install lifecycle scripts execute unsandboxed with tx's permissions.
Imports in your plugin resolve exactly as they do in any other Bun or Node program: exports maps with their subpaths and conditions, imports maps, main, directory indexes, and the node_modules walk, with each dependency resolving its own dependencies the same way. Import a package by the name its exports map publishes rather than by a file path inside it — reaching past the map into a file the package does not publish fails, as it does everywhere else. Nothing is written to your marketplace directory to make this work, import.meta still names your own file, and resolution is the same whether tx is the released executable or a source checkout.
That applies to specifiers written literally, which is how a package is normally named. A specifier assembled at runtime — await import(somePath) — is left as a runtime import and behaves as it always has: a computed path to a file works, a computed package name does not. Write package names literally and you get the resolution above.
A plugin whose graph cannot be resolved does not load, and says which specifier it could not resolve. That is the whole plugin rather than the one import, so a missing dependency is reported when tx starts rather than when the command that needs it runs. Other plugins are unaffected.
tx hands every plugin its own React, Ink, and command parser, so a tx release that upgrades any of them can change the API your plugins are written against. A manifest can say which tx releases it supports, which version of the marketplace this commit is, and which commit carried each released version. All three top-level fields are optional:
{
"version": "1.5.0",
"tx": "^2.0.0",
"versions": [
{
"version": "1.4.0",
"ref": "4f1c0b8e2d9a7c6b5e4d3c2b1a0f9e8d7c6b5a49",
"tx": "^1.8.0"
},
{
"version": "1.5.0",
"ref": "9a8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d3e2f1a0b",
"tx": "^2.0.0"
}
],
"plugins": [{ "name": "notes", "entry": "plugins/notes.ts" }]
}versionis the version of the marketplace this commit is: a semantic version written without avprefix, such as1.5.0or2.0.0-rc.1.tx marketplace listreports it as its last column.txis the range oftxversions this commit supports. Leave it out and the marketplace loads under everytx, pre-releases included — which is how every marketplace that predates the field keeps working. Write*to say so explicitly; an empty or blank value is an error rather than a second spelling of "everything".versionsis the marketplace's release history. Each element names a releasedversion, the full object name of the commit that carried it asref— 40 lowercase hexadecimal characters, or 64 in a SHA-256 repository; never a tag, an abbreviation, or uppercase — and thetxrange that release supports, which is required here. No two elements may carry the same version, and build metadata does not make them different:1.4.0+aand1.4.0+bare duplicates.
Ranges use npm's range grammar exactly as its semver package reads it by default: comparators (<, <=, >, >=, =, or a bare version), X-ranges (*, 1.x, 1.2), tilde (~1.2.3), caret (^1.2.3, where ^0.2.3 stays below 0.3.0 and ^0.0.3 below 0.0.4), hyphen ranges (1.2.0 - 1.9.0), whitespace for "and", and || for "or". Build metadata never affects a match. A pre-release tx matches only a range that names a pre-release of the same major, minor, and patch version: 2.0.0-rc.1 satisfies ^2.0.0-rc.0, but neither >=1.0.0 nor ^2.0.0 — a major release's pre-releases are where its breaking changes land, so a marketplace opts into them by writing the pre-release down.
A field that breaks any of these rules makes the manifest invalid, wherever it is read: marketplace add fails and installs nothing, tx update fails to move to that commit and leaves the marketplace where it was, and loading reports an invalid manifest that names the field and, inside versions, the element's position. A typo is never read as "compatible". Keys tx does not define are ignored, at the top level and inside a versions element, so a later field never breaks an older tx. A tx release that predates these fields ignores them entirely.
When the running tx falls outside a marketplace's declared tx range, none of its plugins load — none of its entries is even imported — and tx reports one diagnostic for the marketplace on every invocation:
Error loading plugin marketplace/installed/tools: Marketplace "tools" supports tx ^2.0.0, not tx 1.8.0. Run "tx update" to update tx and its marketplaces, pin a version that supports tx 1.8.0 with "tx marketplace pin tools <ref>", or set TX_IGNORE_COMPATIBILITY=1 to load it anyway.
A refusal is an isolated plugin failure like any other: every other plugin loads, the command you ran keeps its own exit code, and tx marketplace and tx update keep working. It applies to pinned marketplaces and to local references alike, since what loads is whatever the checkout or the directory holds; a reference's diagnostic names only the override, because there is nothing to update or pin. Nothing about the installation is broken, so removing it is not the remedy.
To load a refused marketplace anyway, set TX_IGNORE_COMPATIBILITY to exactly 1:
TX_IGNORE_COMPATIBILITY=1 tx notesEach marketplace it forces prints one warning line on standard error, so a variable left in a shell profile never goes unnoticed; a compatible marketplace prints nothing. Any other value — true, 0, or an empty one — leaves refusal in effect. The override changes loading only: it does not make an invalid manifest valid, and it never changes which version add or tx update installs.
A user's tx reads the release history from your default branch, and only from there: when its newest commit does not support their tx, it installs the newest release in that history that does (see Versions that support your tx). The history is an index, and each release's own commit is the authority — a release whose commit declares a range the history contradicts is reported, not installed. To keep it accurate, release like this:
-
Set
versionandtxin the release commit, to what that commit is and supports, and tag it if you publish tags. -
Record it in a later commit. A commit cannot contain its own object name, so once the release commit exists, append a
versionselement carrying its full object name and the same range, and commit that to the default branch:git rev-parse 'v1.5.0^{commit}' # the release commit's full object name # add { "version": "1.5.0", "ref": "<that name>", "tx": "^2.0.0" } to versions git commit -am "Record 1.5.0 in the release history"
-
Before the default branch raises
tx, make sure the last release supporting the previous range is in the history. Raising the range is what makes the default branch incompatible with every oldertx; that release is what those users install instead, and without it they have nothing to install.
Every element stays in the history for as long as some tx might need it. To correct or withdraw one, change the default branch — the history any other commit carries is never consulted. Keep each release commit reachable from a branch or tag you publish: tx asks for it by object name, and a remote that no longer has the commit cannot serve it.
A plugin entry is a TypeScript module with a default export. Import the public contract as types only; @fx/tx/plugin does not provide a runtime API.
import type { Plugin } from "@fx/tx/plugin";
const plugin: Plugin = ({ command, context }) => {
command((namespace) => {
namespace.description("Greet people");
namespace
.command("hello")
.description("Say hello")
.argument("[name]", "who to greet")
.option("--loud", "shout the greeting")
.action((name: string | undefined, options: { loud?: boolean }) => {
const greeting = `Hello, ${name ?? "world"}!`;
context.stdout.write(
`${options.loud ? greeting.toUpperCase() : greeting}\n`,
);
});
});
};
export default plugin;Every specifier tx publishes — @fx/tx/plugin and each capability contract below — is published as TypeScript source under a types condition rather than as emitted declarations. That asks one thing of your own tsconfig.json: moduleResolution must be a mode that reads a package's exports map, since that map is the only place these subpaths are described. bundler needs nothing beside it:
{
"compilerOptions": {
"module": "Preserve",
"moduleResolution": "Bundler"
}
}node16 and nodenext work as well, under two conditions TypeScript imposes on those modes rather than on this package. module must be set to the matching Node16 or NodeNext — a mismatch is rejected before anything is type-checked — and the importing file must itself be an ES module, because a type-only import of an ES module from a CommonJS file otherwise wants a resolution-mode attribute; "type": "module" in your own package.json, or an .mts file, settles that. The legacy node resolution ignores exports entirely, so no subpath resolves under it.
Nothing else is required. The contracts name one another by .ts path internally, and TypeScript follows those without allowImportingTsExtensions — you import @fx/tx/grid, not a path into it. Set that option only if your own sources import each other by .ts path, and know what it costs: TypeScript accepts it only alongside noEmit or emitDeclarationOnly, so a plugin emitting its own JavaScript or declarations cannot have it, and nothing about these contracts asks it to.
The initialization API provides an immutable identity, read-only env, the generic command context, shared dependencies, command(build), plugin(childDefinition), register(key, value), registrations(key), update(participant), and updaters(). The context carries process streams, environment, working directory, and the owning plugin identity, so your actions keep whatever signature you give them. Loading, initialization, and command actions may be asynchronous.
Use the initialization API's dependencies.react and dependencies.ink instead of importing separate runtime copies; the injected values share the host's React and Ink instances and include tx and dependency version metadata.
Because your plugin renders with the host's instances, the React and Ink APIs it can use are the ones the running tx ships, and dependencies.versions names them. tx treats a change to either library's public API as a breaking change and releases it as a new major version. tx 2.0 moved from Ink 7 and React 19.2 to Ink 8 and React 19.3; a plugin written against the earlier versions should check:
- Ink 8 requires React 19.3 or newer. tx injects a compatible React, so this only matters if your plugin also installs its own
reactfor types or tests. <Box>minWidthandmaxWidthaccept numbers only.render()options anduseStdin,useStdout, anduseStderrtype their streams as generic Node streams, so terminal-only members such asstdout.columnsare no longer in their types. Read the terminal size withuseWindowSize.useInputno longer receives control sequences that map to no key — mouse reports, focus in and out, cursor-position replies, and similar terminal replies are discarded before any handler runs. A plugin that read those fromuseInputmust read them some other way.
Plugins can share plugin-owned runtime capabilities through an opaque keyed registry. The public contract is generic and types-only:
register<T>(key: string, value: T): void
registrations<T>(key: string): readonly T[]A provider declares its own structural type and registers a value during initialization. Registering a value alone claims no command namespace:
import type { Plugin } from "@fx/tx/plugin";
interface Formatter {
format(value: string): string;
}
const formatter: Formatter = {
format: (value) => value.toUpperCase(),
};
const plugin: Plugin = ({ register }) => {
register<Formatter>("formatter", formatter);
};
export default plugin;A consumer declares a compatible local type. Read inside a command action when the consumer needs every provider, because initialization is still in progress while plugins are loading:
import type { Plugin } from "@fx/tx/plugin";
interface Formatter {
format(value: string): string;
}
const plugin: Plugin = ({ command, context, registrations }) => {
command((namespace) => {
namespace.action(() => {
const formatters: readonly Formatter[] =
registrations<Formatter>("formatter");
for (const formatter of formatters) {
context.stdout.write(`${formatter.format("hello")}\n`);
}
});
});
};
export default plugin;The registry contract is deliberately small:
- Keys are opaque strings compared by exact equality. tx does not reserve, trim, normalize, parse, namespace, or version them.
- Values are stored and returned unchanged. tx does not inspect, validate, invoke, clone, or freeze them; the generic type supplied to
registrations<T>is only the caller's TypeScript assertion. - Every registration remains present, including repeated keys and repeated values. Reads return matching values in FIFO commit order, preserving each plugin's call order and root/child initialization order; there is no selected winner.
- Each read returns a fresh frozen array containing entries committed at that moment. An absent key returns a fresh frozen empty array. The array is immutable, but the opaque values inside it are untouched.
- A plugin's registrations are staged with its commands, children, and update participants. They commit only after successful initialization and namespace validation; any loading, initialization, export, namespace, or collision failure discards the complete stage.
- A read during initialization sees earlier committed plugins only, not the reader's own stage or later plugins. A command-time read sees every provider that initialized successfully.
- Registration closes when initialization finishes. Calling
registerlater is rejected; committed entries are append-only.
This is not a dependency-injection or lifecycle container. There are no schemas, runtime type checks, key factories, symbol tokens, ownership metadata, collision or duplicate policy, provider selection, priorities, versions, scopes, unregistering, replacement, subscriptions, events, factories, dependency ordering, disposal, health checks, retries, or caching. Failures while a consumer uses an opaque value belong to that consumer.
The namespace-free bundled config provider registers one capability under the exact opaque key @fx/tx/config. It persists small JSON values across invocations in one per-user document. Import the contract from that same key rather than restating it — the string you read the capability from and the string you import its shape from are one string, so a contract that moves fails your build rather than your command:
import type { Config, ConfigValidator } from "@fx/tx/config";Config is what the key carries: define(key, isValid), read(key) resolving the persisted value or undefined, and write(key, value). A ConfigValidator<T> is your own (value: unknown) => value is T, which is the whole of what makes a read safe — the capability never infers one, because only the consumer knows what its key means. Every member is documented where it is declared, and the contract is types only: it publishes no way to obtain a store, which stays the registry's job, and nothing behind the import is a file, a path, or a document format.
A consumer reads registrations<Config>("@fx/tx/config") inside its command action, after initialization has committed every provider. What a read answering none, or more than one, means is the consumer's own decision: the contract types the values under the key and neither supplies one, selects among them, nor rejects one. The marketplace plugin decides it strictly — requireConfigCapability treats both counts as errors naming the count, with no fallback — because the config plugin is composed by default, so a tx without it is misconfigured rather than degraded. A consumer with a reason to tolerate an absent provider is free to make the opposite choice.
Call define once for each key before reading or writing it in the current process. Keys are opaque and compared exactly: tx does not trim, normalize, parse, namespace, or reserve them. A second definition of the same key is rejected and leaves the first guard in force. An absent property reads as undefined; a present value and every value being written must pass that key's guard. A rejected read affects no other key, and a rejected write changes nothing on disk. Values use JSON encoding, so a guard should accept only values that survive a JSON round trip in the form the consumer expects.
The document is named config.json in the platform's tx user-data directory:
$XDG_DATA_HOME/tx/config.jsonwhenXDG_DATA_HOMEis an absolute path, otherwise~/.local/share/tx/config.json, on Linux and other non-Windows, non-macOS platforms.~/Library/Application Support/tx/config.jsonon macOS.%LOCALAPPDATA%\tx\config.jsonon Windows, falling back to%APPDATA%\tx\config.json, then~/AppData/Local/tx/config.json.
The file may be absent and is safe to hand-edit or pre-seed. Its top level must be a JSON object whose properties are config keys. Invalid JSON and every non-object root are reported rather than replaced. A write preserves every unrelated property, creates missing parent directories, and atomically replaces the document through a uniquely named temporary file beside it. Concurrent processes therefore leave a complete valid document, but they are not locked: both may read the same old object, and the later whole-document replacement may silently lose the earlier writer's change. Consumers needing merged concurrent writes need a different store.
There is no tx config command, key listing or deletion API, schema language, migration mechanism, encryption, or cross-process transaction.
The namespace-free bundled theme provider registers one capability under the exact opaque key @fx/tx/theme. It is the one place tx decides what its terminal output looks like: a surface names what a piece of text is and the theme answers with an appearance. Import the contract from that same key rather than restating it — the string you read the capability from and the string you import its shape from are one string, so a contract that moves fails your build rather than your command:
import type {
Appearance,
Hue,
Theme,
ThemeVariable,
Theming,
} from "@fx/tx/theme";
// A partial override any plugin may contribute, published at the separate key
// it is registered under.
import type { ThemeOverride } from "@fx/tx/theme-override";Theming is what the key carries: theme(stream, options?) resolving a Theme, which answers appearance(variable) with an Appearance of optional dim, bold, inverse, and hue. A ThemeVariable is one of nine semantic roles — chrome, content, cursor, marker, muted, strong, positive, caution, and danger — and a Hue is one of nine colours: the eight ANSI ones plus gray. Background hues, 256-colour, and truecolour are deliberately absent. Every member is documented where it is declared, and the contract is types only: it publishes no way to obtain a theme, which stays the registry's job.
A consumer reads registrations<Theming>("@fx/tx/theme") inside its command action, after initialization has committed every provider. It must find exactly one — as the marketplace plugin's requireConfigCapability lookup already chooses to, and unlike the dialogs capability, where the consumer owns what an absent capability means: none and several are both errors naming the count, and there is deliberately no fallback, because a consumer that fell back would have to carry its own copy of the default theme. The theme plugin is composed by default, so a tx without it is misconfigured rather than degraded.
A theme is resolved for the stream a surface draws to rather than handed out ready-made, because whether hues are emitted depends on that stream. Only the stream's TTY-ness is read; the capability never writes to it, retains it, or exposes a terminal or renderer. A resolved theme answers with an appearance alone and never says whether hues were enabled — that decision is already inside every appearance it returns.
An appearance asserts only what it carries: an absent dim, bold, or inverse means the attribute is not applied, and an absent hue means no hue is emitted. The default theme is the greyscale Norton Commander look the dialogs already had — chrome, muted, and marker dimmed, content, positive, caution, and danger in the terminal's default foreground, strong bold, and cursor inverted — and it names no hue anywhere, so a tx that overrides nothing emits only the terminal's own foreground and background, their dimmed and bold forms, and their inversion.
Any plugin may contribute a partial override by registering a ThemeOverride under the separate opaque key @fx/tx/theme-override. Overrides are composed over the defaults when a surface resolves a theme, which is while a command runs, so an override contributed by a plugin composed after the theme plugin still applies; a plugin that fails initialization contributes none. A variable is the unit: an unspecified one keeps its default, a contributed appearance replaces the default rather than merging into it, and a later override of the same variable wins in the registry's commit order. Overriding is supported because a surface will occasionally need it, not because varying the look is encouraged.
Whether hues are emitted is decided by five inputs in one fixed order, the first that decides settling it with the rest unread:
- The
colouroption, where the invoking command supplied one. Only exactlytrueor exactlyfalsecounts as a request; an omitted option and anundefinedfield are passed over. NO_COLORpresent in the environment with any value, an empty one included, disables hues.FORCE_COLORdecides in both directions:0andfalsedisable hues even on a terminal, and any other value enables them even off one. Absent, empty, or only whitespace decides nothing.TERMbeingdumbdisables hues.- The stream not being a terminal disables hues. A stream counts as a terminal only where its
isTTYis exactlytrue; an absentisTTYis not a terminal.
Where nothing decides, hues are enabled. Two consequences follow from the order: NO_COLOR beats FORCE_COLOR, and FORCE_COLOR=1 beats both TERM=dumb and a redirected stream, which is what makes it a way of forcing colour rather than a hint. With hues disabled a theme still resolves dim, bold, and inverse, so a surface keeps its structure when it loses its colour.
A user-selectable theme, a theme name, a config key, persistence, background hues, 256-colour and truecolour, underline, italic, and blink are all out of scope, and glyph choice is not a theme variable.
The namespace-free bundled dialogs provider registers one capability under the exact opaque key @fx/tx/dialogs. It asks the person in front of the terminal a question and answers with what they chose. Import the contract from that same key rather than restating it — the string you read the capability from and the string you import its shape from are one string, so a contract that moves fails your build rather than your command:
import type {
Dialogs,
EmbeddedProps,
FilterMode,
InputProps,
InputRequest,
SelectOption,
SelectProps,
SelectRequest,
SelectResult,
TextField,
} from "@fx/tx/dialogs";Dialogs is what the key carries: input(request) collecting one line of text and select(request) driving a column browser, each resolving undefined where the reader cancelled, and Input and Select, the same two dialogs as components for a plugin that draws its own interface — see Embed a dialog in your own interface. A SelectRequest carries the message, the options, optional headers for a column of cells, an optional filter of "typed" or "always", an optional expand of "enter" or "tab", and an optional multiple that lets the column tick several options. A SelectOption declares exactly one of a label or a row of cells, the opaque value it stands for, the TextFields it collects, the dialog it opens — a nested request or a single field — and whether it opens selected, a pre-tick meaningful only in a column declaring multiple: selected: true on an option of a column that does not declare multiple is rejected before anything renders, while selected: false is accepted in any column and means the same as omitting it. A SelectResult carries the completing option's value, the values collected on the way to it, and the values selected — see Tick several options. Every member is documented where it is declared, and the contract is types only: it publishes no way to draw a dialog, which stays the registry's job, and nothing behind the import is a renderer, a matcher, or React's element type. The provider's own rendering vocabulary is deliberately not published — a consumer that calls select never sees a rendered element, and publishing one would make an internal rendering decision a breaking change.
A consumer reads registrations<Dialogs>("@fx/tx/dialogs") inside its command action, after initialization has committed every provider. What a read answering none, or more than one, means is the consumer's own decision: the contract types the values under the key and neither supplies one, selects among them, nor rejects one, and tx defines no winner semantics. The grid plugin decides it strictly — requireDialogsCapability treats both counts as errors naming the count — because a consumer that fell back would have to own movement, filtering, a viewport, and a terminal session of its own. A consumer with a reason to tolerate an absent provider is free to make the opposite choice.
Every dialog requires both the provider's injected standard input and standard error to be TTYs and rejects a non-interactive stream before rendering or changing terminal state; there is no fallback. It then resolves a theme for its standard error stream through the theme capability above, so a tx composed without exactly one theme provider fails the dialog with an error naming the count rather than drawing an appearance of its own. Dialogs use the injected React and Ink instances, read only injected standard input, and render only on injected standard error, so standard output stays untouched for the consuming command.
select additionally rejects an empty options list before rendering, and renders the message plus the label of every option the filter leaves visible that its viewport has room for, in supplied order. Labels are display text; values are opaque and returned by exact identity, with duplicates retained and the first option initially active.
Up and Down move one position among the visible options and clamp at the first and last of them. Home and End make the first and the last visible option active, and Page Up and Page Down move by the number of option rows on screen, clamped the same way. Enter on a plain option resolves { value, values, selected }, where value is that option's exact value, values is empty, and selected is [value] unless a column ticks. Escape and Ctrl-C return undefined at every stage; the provider does not terminate the process, assign an exit code, or print the selected value. Input the dialog has no meaning for is ignored; a printable character is never one of them, because typing always reaches the filter — apart from the Space keystroke a column declaring multiple takes for ticking. Keys typed faster than the terminal is read arrive in one chunk, and a carriage return inside one is the Enter it was: gam and Enter arriving together filter and then take, exactly as they do typed apart, and in an input the text before the return is appended and submitted.
An option may declare a sub-dialog under dialog: either a nested select request (its own message, options, and optional filter) or a single text field. An option that declares one is marked with ▸ on the right edge of its column, and opening it adds a column to the right of the one it was opened from rather than a panel over it. Enter opens the marked option by default — the key that takes a plain option opens one that leads somewhere, which is what the marker promises — and the right arrow opens under any binding. The root request's expand field rebinds opening to "tab", which keeps Enter meaning "take this" at every level; it is read from the root request only, so one dialog answers one set of keys however deep the reader goes. Without a declaration every one of those keys is a no-op on that row and the filter text is left untouched, and typed or pasted text never opens anything. The left arrow backs out into the column that opened this one and does nothing at the leftmost column, where Escape rather than an arrow is what closes the dialog. Escape pops one column while anything is open and cancels only at the root; Ctrl-C does the same. Every column keeps its own filter text and active position, so opening one starts it blank on its first option while the ones behind it keep what they were showing, and backing out restores exactly what they showed. Completing any column resolves the whole path: the finally-Entered option's value plus every input value collected along the way, merged by field name with deeper submissions winning collisions. A text leaf resolves with its opening option's value and its submitted text under its field's name. Every reachable sub-request is validated before rendering alongside the existing rejections — an empty nested list, an empty field list, or a repeated field name within one nested option renders nothing. The hint line names exactly the keys the dialog answers where the reader is: at the leftmost column, ↑↓ move · →/Enter open · type to filter · Esc cancel on a row that leads somewhere and ↑↓ move · Enter select · type to filter · Esc cancel on one that does not; once a column has been opened, ←/Esc back joins the line and Esc cancel leaves it, because Escape backs out of a column rather than cancelling the dialog; and while the column taking keys ticks, Space tick follows ↑↓ move. Every column is still one render session with the same cleanup contract.
The columns render inside one frame — the first level's — in greyscale only. A sub-dialog has no border, offset, or shadow of its own, so a path three levels deep is still one bordered panel with three lists side by side, separated by a dimmed │. The columns share one band of rows — nothing but option rows is in it, since the filter and the counts live in the frame's edges — so a list of three and a list of thirty start on the same row, and a column whose filter matched nothing spends its one row saying no match. Every column draws the list it was showing with its cursor bar still on the choice it was left on, and every bar is drawn the same way — the inversion alone, with no shading to set the driven column's apart. Which column is being driven is said by where it sits: it is the rightmost. A column behind the driven one is dressed at rest: nothing on it animates, and its own filter text and hidden counts are not drawn, because the edges that carry those belong to the column taking keys. The panel's title is the trail of the columns on screen, joined with ›. When the columns run out of room the leftmost is dropped first, and the title says so with a leading …; collapsing stops at one column, which is truncated to what is left rather than dropped. A text leaf's entry renders as its own panel beneath the frame, exactly as a collected field does.
Typing always filters. A printable character narrows the column the reader is in, at every level and whatever the list's length; there is no setting that makes typing do nothing. filter decides only whether the filter is on screen before anything has been typed into it: "typed", the default, keeps it off screen until it is used, and "always" shows it from the moment the dialog opens. Because it is set into the frame's bottom edge rather than drawn as a row, it appearing costs the panel no row and moves nothing in the list.
The filter is the element typed text reaches from the moment the dialog opens; no key moves focus to or from it, and the arrows, Enter, Escape, and Ctrl-C keep the meanings they have without it. Printable characters and Backspace edit the filter text exactly as they edit an input value, and the current text is rendered after a › prompt. The text's whitespace-separated pieces are its terms: an option is visible when every term occurs in its label under a case-insensitive comparison, so rel 1.4 finds release/1.4 in any term order. Matching is substring only — there is no fuzzy matching, ranking, match highlighting, matching against values, caller-supplied matcher, or initial filter text — so visible options keep the order and the duplicates the caller supplied. An option that declares fields is the caller's "let me type it" answer and stays visible whatever the text, since typing something nothing matches is exactly when it is needed. Changing the text makes the first visible option active. When nothing is visible the dialog renders no match, Enter and navigation do nothing, and Escape still cancels — Escape never clears the filter instead. Field collection stops filter edits along with navigation, and the filter text never appears in the result.
Every select renders its options through a viewport, filtered or not, so a long list neither overflows the terminal nor makes rendering cost grow with the option count. At most ten option rows appear at once, and fewer when the terminal is short: the window shrinks so that the whole dialog — its two frame edges and its key hints — stays shorter than the terminal, which is what keeps it from clearing or scrolling away what was on screen before it opened. Choosing a user-provided option puts that field's own frame on screen underneath, so the window gives rows back on the frame that first draws it rather than reserving them the whole time; a terminal too short for one option row once the field arrives simply shows none while the field is collected. In a terminal too short for even one option row plus those other rows, the window gives up its last row rather than fill the screen: the dialog keeps its edges and the counts set into them, still navigates, and still settles on a choice it can no longer draw, because a window the reader cannot see beats a terminal wiped out from under them. The window moves only as far as keeping the active option on screen needs, so the list stays still under the cursor bar rather than recentering on every keystroke, and it follows the terminal: a resize re-derives it. When visible options sit outside the window the dialog says so on that side and counts them, as ▲ N set into the frame's top edge and ▼ N into its bottom. They live on the edges rather than in rows of their own, so one appearing as the reader scrolls past the first hidden row moves nothing; the room for them is held from the first frame, so the title does not resize either. The window is over the visible options, so it composes with the filter: its rows and its hidden counts describe what the filter left, not the list the caller supplied.
An option that declares fields is user-provided: choosing it collects those values instead of resolving immediately, so one dialog can offer known choices alongside "let me type it". An option declaring no fields is plain and resolves with an empty values record, which is how a caller tells the two apart. select rejects an option whose field list is empty, or that repeats a field name within itself, before rendering — alongside the empty-options and non-interactive rejections. Field names need only be unique within their own option, and only the chosen option is ever collected.
Fields are collected one at a time in declared order, each using the input behavior below, including its own initialValue. The next field appears only after the previous one is submitted, and the option list stops accepting navigation and selection the moment collection begins. After the last field, select resolves with the chosen option's exact value and one collected value per declared field, keyed by the field's name rather than by its displayed message. A name is an opaque key and may be any string, including one that shadows an inherited object property such as __proto__; the collected record carries it as an own property either way. Escape or Ctrl-C at any stage cancels the whole dialog, resolves undefined, and discards everything already collected: there is no return to the option list, no back-navigation key, and no partial result. A field's type is the extension point for a later field kind; text is the only one that exists, and there is no form presenting several fields at once, no focus movement, and no validation — a caller validates what it receives.
input collects a single line of text. It renders the message and the current value, starting from initialValue when one is supplied and from an empty value otherwise. Printable characters append in typed order; input arriving as one multi-character chunk, as a paste does, appends whole, minus any control characters it carries. Backspace drops the last character, counted by code point so a non-BMP character leaves whole, and does nothing when the value is empty. Any other input leaves the value unchanged: arrow keys, Tab, and Ctrl and Alt combinations append nothing. A complete control sequence appends nothing whether or not it names a key, because Ink discards the ones no key represents — focus reports, cursor-position replies, unmapped function keys — before a handler runs. Text that only looks like one, [25~ typed or pasted on its own say, appends like any other text. A modifier does not change what Enter, Escape, and Backspace themselves do, matching select — Alt-Enter still submits, and a double Escape still cancels. Enter returns the value exactly as entered, including the empty string, so an intentionally empty value stays distinguishable from the undefined that Escape and Ctrl-C return. The provider never trims, validates, or transforms the value and never writes it to standard output; whether an empty value is acceptable is the consuming command's decision. There is no caret movement, entry history, completion, or masking.
Both dialogs are drawn the way Norton Commander drew its panels, in greyscale. Each is a framed panel carrying its message as a title set into the top edge — the request message for a select or a standalone input, the field's own message for a field under collection — with a select in a double-line frame and an input or a field in a single-line frame. The active option is an inverted bar spanning its column's width rather than a marker character — and the rightmost column takes whatever the title and the edges left the panel spare, so a select showing one column has its bar spanning the whole frame — and the frame edges, the title, the › filter prompt, the ▲ N and ▼ N overflow counts, and the key hint line are dimmed relative to option labels and entered text. That is the whole palette: the terminal's default foreground and background, their dimmed form, and their inversion. No hue is ever emitted, so a dialog looks the same on a light theme, a dark one, a sixteen-color terminal, and a true-color one, and there is nothing to configure.
A dimmed key hint line follows the lowest frame on screen — exactly one of them, however many columns are on screen: ↑↓ move · Enter select · type to filter · Esc cancel under a select, with the phrases the current column and the row under the bar answer as described above, and Enter submit · Esc cancel under a standalone input or a field collected at the leftmost column, which is the line shown while such a field is collected because navigation and filtering have stopped by then. An entry opened over a column — a text-field sub-dialog, or a field of an option chosen in a column that was opened — reads Enter submit · Esc back instead, because its Escape closes that entry and returns to the column that opened it rather than cancelling the dialog. It is the same rule the select's own line follows, minus the left arrow an entry does not answer. A frame is as wide as the wider of its title and its widest row, and never wider than the terminal; twenty columns is the narrowest terminal it lays out for, and how a narrower one wraps the result is unspecified. Nothing wraps: a title or a label too wide for the frame is truncated at its end with an ellipsis, while filter text and a value under entry are truncated at their start so their tail and the █ caret drawn after them stay in view. Wrapping is what the truncation avoids — a label spilling onto a second row would change the number of rows the viewport counted on.
Three things move, and nothing else does. The █ caret after entered text and after the filter alternates between visible and hidden about twice a second while the dialog waits for input, keeping its cell either way so the panel never resizes on its own timer; typing puts it straight back on its visible phase, so a keystroke is never answered by a row that looks like it lost its caret. Only a line that still answers keystrokes carries one: the filter keeps its text and its › prompt once a field is being collected, but gives up its caret, because it has stopped accepting edits by then and the field below it is the row being typed into. An overflow indicator pulses between its dimmed and normal rendering on the same phase, and only while it is on screen at all — that is, only while the window is hiding rows. Confirming a plain option flashes the cursor bar before the dialog settles: the choice is recorded the moment Enter is pressed, every key from then on is ignored — Escape and Ctrl-C included, because the choice is already made — and the dialog settles well inside the 250 milliseconds the spec allows, on elapsed time rather than on any particular frame. Field collection is not confirmation and does not flash; it moves straight to the field. Neither does a confirmation in a terminal too short to draw an option row, since there is no cursor bar on screen to flash — it settles at once rather than spending the flash ignoring input over a frame that would not change.
A dialog animates on one subscription for all three, which is active exactly while a caret, an indicator, or a flash is on screen. So a select with no filter on screen, nothing hidden, and nothing confirmed runs no timer and writes nothing at all while it waits: it is on screen and quiet, not idling in a redraw loop. Animation never delays input either — a keystroke is reflected in the very next render whatever phase the caret is in — and the subscription belongs to the render session, so the unmount in the cleanup contract below is what stops it and no timer outlives a settled dialog.
Both dialogs are built on the same render session and obey the same cleanup contract, and a select that collects fields is one such session for the whole interaction: it does not unmount, restore terminal state, or settle between its selection and field stages. Completion, cancellation, rendering failure, and interaction failure all finish renderer unmounting, restoration of the prior terminal/input state, listener teardown, and pending output before the promise fulfills or rejects. If an injected raw-mode disable, unref, or renderer unmount method persistently throws, the provider retries finitely and rejects with the first applicable cleanup failure; restoration or renderer teardown is necessarily best-effort only on that exceptional path. There is no non-interactive fallback, concurrency policy, nested-dialog support, or multi-provider selection policy.
A column ticks when its request declares multiple: true. The setting belongs to that column, as headers and filter do: a nested request decides its own, and an omitted one leaves the column single-choice, so a column browser can take several things at one level and one thing at another. Every row of a ticking column starts with a tick cell — □ unticked, ■ ticked, followed by a space — drawn as the theme's marker variable and as part of the cursor bar on the active row. A header row is offset by the same two columns so each name stays over its field, and a column too narrow for its rows gives up the end of its labels or fields before its tick cell.
Space — exactly one space character with no modifier — toggles the tick on the option under the bar and never reaches the filter in such a column. A chunk carrying a space among other characters, as a paste does, still filters whole, while a space followed by a carriage return in one chunk — Space and Enter typed faster than the terminal was read, as happens over a slow link — ticks and then takes; and in a column that does not tick Space is an ordinary filter character. With nothing visible Space does nothing. Ticking moves nothing, opens nothing, and collects nothing, so an option that leads somewhere or declares fields can be ticked and still opened or chosen with its usual keys. A tick belongs to the column it was made in: it survives the filter hiding its option, and a column closed and re-opened from the same option shows the ticks it was left with. Cancelling discards every tick.
An option opens ticked by declaring selected: true, which is accepted only in a column declaring multiple: select and the embedded Select reject one anywhere else, at any depth, before drawing anything. selected: false means exactly what leaving it out means and is accepted everywhere.
Ticking adds no way to finish. Enter on a plain option, a finished field collection, and a submitted text leaf complete the dialog exactly as before, and Enter still flashes the bar. Every SelectResult then carries selected: the values of every ticked option in every column opened during the dialog, backed out of or not — by column in the order the columns stand in the request, a column before the columns under its options, and in supplied order within each, ticked options the filter hides included — or, only where no opened column holds a tick, the completing option's value alone. A column the reader never opened contributes nothing, its pre-ticks included. So one dialog can list kinds of thing at its root and the things of each kind beneath them, and take every kind's ticks on one Enter; your values are opaque, so tell which column a value came from by the value itself. value stays the completing option's value whether or not it is ticked, and values holds only the fields collected on the path to it, so a ticked option's own fields are never collected; ask for input per ticked option after the dialog if you need it. A dialog with no ticking column always resolves selected as [value], so a caller that ignores it reads the result it always read.
const hosts = await dialogs.select({
message: "Which hosts?",
multiple: true,
options: [
{ label: "alpha", value: "alpha" },
{ label: "beta", value: "beta", selected: true },
{ label: "gamma", value: "gamma" },
],
});
// Enter at once: { value: "alpha", values: {}, selected: ["beta"] }selected is a required member of SelectResult, so a test double of your own that constructs one has to fill it; [value] is what the provider resolves for a dialog in which nothing is ticked.
A plugin that draws a full-screen interface of its own — a chat client, a dashboard — already holds the terminal in a render session it started with the injected Ink, and cannot hand it to select or input: each starts a second session on the same terminal, and the two fight over raw mode, the input stream, and the screen. Render the components instead. dialogs.Select and dialogs.Input are the dialogs select and input mount — the same filter, viewport, columns, presentation, and keys — rendered inside your session, placed by your layout, and focused by you.
Every embeddable component that takes keys takes the same props, EmbeddedProps<R> plus its request, so you learn them once:
request: exactly what the function form takes. A component presents the request it was mounted with; to ask a different question, mount a new component (give it a newkey).width: the terminal columns it may draw in. It never reads the terminal's width, and below twenty it lays itself out as if given twenty.height(Selectonly): the terminal rows it may draw in, its edges, hint line where one is drawn, and any field panel beneath it included. The window gives up option rows to fit, and none at all whereheightcannot afford one.selectpasses the terminal's rows less one, the row that keeps a dialog strictly shorter than the terminal, so aheightone short of your terminal reproduces it exactly.Inputtakes no height: it is always three rows of frame and, unlesskeyHintsis false, its hint line.isActive: whether it answers keys. An inactive component draws exactly what it would draw active — same rows, same hint line, so moving focus moves nothing — but no caret, and runs no animation, so it never redraws on a timer. A confirmation flash already under way still runs out and callsonSubmit.keyHints(optional, defaulttrue): whether it draws its key hint line. Turn it off when your interface shows its own key help: the line under the frame goes, and so does the one under any field or text leaf aSelectcollects; aSelectgives that row to its option rows; and the component is laid out in its frame's width alone, so whatever you place beside it starts right after the closing border. You then own telling the reader the keys.selectandinputalways draw theirs.onSubmit(result): called with exactly what the function form resolves with — aSelectResult<T>or the entered string.onCancel(): called where the function form resolvesundefined.
A component calls one of the two at most once. After that it ignores every key and keeps drawing its last frame until you unmount it, so unmount it, or mount another, when you have your answer. Callbacks are read on every call rather than captured at mount, so passing fresh closures on each render is fine and costs the component nothing. Every read of the capability yields the same two functions, so rendering one again with new props keeps its state — its filter text, open columns, and active option.
A component paints only the cells it draws: each frame row up to its closing border, the hint line from its first column to its last character, and an entry panel under a select to its own frame and hint line rather than to the select's. Draw it over content of your own and that content is hidden exactly there, so there is nothing to clear behind the component, and shows through everywhere else — beside a frame narrower than its hint line, after the hint line's last character, and beside the narrower of a select's frame and the entry under it.
A component reads and writes no stream and changes no terminal state: every key arrives through your session and everything is drawn by it, and restoring the terminal is yours. It does not require interactive streams either, since it never touches them, but it does reject on its first render every request select rejects, by throwing before it draws anything — which your session's error handling sees like any other render failure. It resolves its theme through the theme capability once per mount, so a tx without exactly one theme provider fails that render with the same error. Ctrl-C reaching it cancels it exactly as it cancels select, but whether Ctrl-C reaches it is your session's choice: Ink's default exitOnCtrlC ends the session before any input handler runs, so render with exitOnCtrlC: false if you want the dialog to see it. Only an active component answers keys, so you may mount several and move focus between them; make two active at once and both answer the same keystroke.
The contract types the components as functions of their props returning unknown, because it is types only and names no React type. Your plugin holds the injected React that renders them and has React's types — @types/react is a dependency of @fx/tx — so cast once where you call createElement, as you would Grid:
import type { Dialogs, SelectProps, SelectResult } from "@fx/tx/dialogs";
import type { Plugin } from "@fx/tx/plugin";
import type { ReactNode } from "react";
const plugin: Plugin = ({ command, dependencies, registrations, context }) => {
const { react, ink } = dependencies;
command((namespace) =>
namespace.action(async () => {
const [dialogs] = registrations<Dialogs>("@fx/tx/dialogs");
if (!dialogs) throw new Error("dialogs capability missing");
// The one cast: the contract says `unknown`, the injected React says
// what a component returns.
const Select = dialogs.Select as (
props: SelectProps<string>,
) => ReactNode;
const App = () => {
const { exit } = ink.useApp();
const { columns, rows } = ink.useWindowSize();
const [picking, setPicking] = react.useState(true);
const [picked, setPicked] = react.useState<string>();
// The host's own keys: Tab moves focus between its panel and the
// dialog, and q quits once the dialog does not have it.
ink.useInput((input, key) => {
if (key.tab) setPicking((current) => !current);
else if (!picking && input === "q") exit();
});
return react.createElement(
ink.Box,
{ flexDirection: "column" },
react.createElement(ink.Text, null, `Picked: ${picked ?? "nothing"}`),
// Unmounted once answered: a component is one-shot, and a host
// wanting another answer mounts another.
picked === undefined &&
react.createElement(Select, {
request: {
message: "Which branch?",
options: [
{ label: "main", value: "main" },
{ label: "release/2.0", value: "release/2.0" },
],
},
width: columns,
// One row for the line above, one to stay under the terminal.
height: rows - 2,
isActive: picking,
onSubmit: ({ value }: SelectResult<string>) => {
setPicked(value);
setPicking(false);
},
onCancel: () => setPicking(false),
}),
);
};
const session = ink.render(react.createElement(App), {
stdin: context.stdin,
stdout: context.stderr,
exitOnCtrlC: false,
});
await session.waitUntilExit();
}),
);
};
export default plugin;Input is rendered the same way with InputProps — request, width, isActive, the optional keyHints, onSubmit(value), and onCancel() — and cast to (props: InputProps) => ReactNode. Render both with the React and Ink tx injected into your plugin; rendering one with any other copy of either is unsupported.
The namespace-free bundled grid provider registers one capability under the exact opaque key @fx/tx/grid. It exists so that a plugin with rows to show does not have to own column measurement, display-width arithmetic, colour resolution, canvas sizing, or a renderer lifecycle. Its contract is published at that same key, so you import it rather than restating it:
import type {
Cell,
Grid,
GridAction,
GridProps,
GridRequest,
GridSelection,
GridSelectRequest,
GridSelectRow,
OutputStream,
Row,
SelectGridProps,
} from "@fx/tx/grid";Grid is what the key carries: print(request) writing a GridRequest — a stream, an optional layout of "table" or "flow", optional headers, the rows, an optional empty message, and an optional summary — and select(request) driving a GridSelectRequest of a message, optional headers, and GridSelectRows, each carrying its cells, the value identifying it, and the GridActions it offers, resolving to a GridSelection of the chosen value and action or to undefined. It also carries Grid, the printed grid as a component taking GridProps, and SelectGrid, the driven grid as a component taking SelectGridProps, both described below. A Row is a list of Cells or bare strings, and an OutputStream is anything that can be written to and may report its columns and isTTY.
A consumer reads registrations<Grid>("@fx/tx/grid") inside its command action, after initialization has committed every provider. The contract is types only, and it declares a cell's variable as Theming's own ThemeVariable by importing @fx/tx/theme rather than restating that vocabulary, so a variable renamed there is renamed in every cell that can name one. The grid resolves a theme for the stream it is printing to through the theme capability above, so a tx composed without exactly one theme provider fails the call with an error naming the count rather than choosing an appearance of its own. It uses the injected React and Ink instances and never reaches for the process's own streams.
A cell supplied as a bare string is exactly the cell that string would make with no variable and no alignment, so a row may mix the two notations freely. An absent variable names content; an absent align names start. Every string the grid renders — a cell's text, a header, the empty message, the summary, a selecting request's message, and an action's label — has its control characters removed before it is measured or drawn, and that removal is applied to every string it hands the dialogs capability too, so text carrying a newline or an escape sequence can neither break the layout apart nor reach the terminal as a command, and nothing else about the string is changed. Text is measured in terminal display columns rather than code units. A cell left empty after that removal renders as —; a header, an empty message, and a summary are the consumer's to leave blank and never get the placeholder. A grid's column count is the most cells any one row supplies, or the number of headers where there are more of those, and a short row's missing trailing cells render as the placeholder rather than shortening the row.
A table aligns every cell of a column to the widest cell in it, the header included, separates columns by two spaces, and pads the final column not at all, so the grid adds no trailing whitespace to a line. That is what not padding achieves rather than a licence to trim: a cell whose own text ends in spaces still prints with them, exactly as every other character it was handed does. A cell declaring end is padded at its start instead, which is what lines a column of counts up on its digits. A supplied header row is drawn once above the rows and emphasized; a supplied summary is drawn once beneath them, de-emphasized and separated by one blank line. A grid with no rows prints its empty message where the rows would have been and no header row over nothing, and a summary is separated from that message by the same blank line; a grid with no rows and no empty message prints a supplied summary alone. A grid with nothing to say writes nothing at all.
A flow is the same cells with no column meaning: the cells of every row flattened in row then cell order, placed into as many equal columns as the width affords and read down each column before across, one column when it affords no more. A flow ignores a supplied header row and a cell's declared alignment — neither has anything to mean without columns of fixed meaning — while a cell's declared variable is still honoured. The empty message and the summary behave exactly as they do in a table, so the two layouts differ only in how the cells are placed. A request declaring no layout is a table, which is the only layout that needs no width at all.
Printing writes to the stream on the request and never to the process's own standard output or error, and it does not require that stream to be interactive. It renders once and returns: no input handler, no alternate screen, no patched console, and no cursor-positioning, screen-clearing, or repaint sequence in what it wrote. The width a width-dependent layout decides against is the one the stream reports, and a stream whose columns is absent is read as eighty, so a flow through a pipe still produces one determinate answer. The canvas is sized from the measured grid rather than from the terminal, so the bytes printed are the same on a terminal and through a pipe apart from the hues the colour decision above drops.
select is the same cells driven rather than printed. It presents the rows as the options of a select supplied by the dialogs capability above, so movement, filtering, the viewport, the cursor bar, and cancellation are exactly that capability's and nothing about them is re-implemented or re-specified here — including its rejections, which it raises before any terminal state changes: a grid with no rows, rows carrying no cells at all, and the non-interactive standard input or standard error a dialog cannot run on. It reads the dialogs capability while your command runs, exactly as it reads the theme, and fails with an error naming the count where a tx is composed without exactly one dialogs provider. A selecting request carries no stream: the dialog draws through the streams it was injected with, which is what the handover guarantee below depends on.
Every row carries the value that identifies it, so a row you cannot identify is unrepresentable rather than rejected, and there is no list running parallel to the rows to fall out of step with them. Rows are padded to the grid's column count with the same — a printed one uses, so a set of rows differing in cell count is laid out rather than rejected. A cell's declared variable and align do not survive: a select takes an option's cells as display text and draws its cursor bar as the inversion alone, so every cell of a selectable row is drawn as content whatever role it declared. Put a row's state in a cell's text where it has to be visible while selecting.
A row's actions are the sub-dialog that row opens, so acting on a row is the drilling sub-dialog columns already own rather than a second mechanism beside it — Enter or → opens the actions of the row under the bar, ← or Esc backs out to the rows, and no key is introduced. Actions are declared per row, so two rows may offer different ones; an empty list means the row declares none, exactly as omitting it does, and such a row is taken by Enter and resolves on the row alone. A selection reports both halves — the chosen row's value and the chosen action — so you never reconstruct one from the other. An absent action means the chosen row offered none: backing out of an actions column returns to the rows rather than selecting the row without one. Absent means the key is not there, so test it with "action" in chosen rather than chosen.action === undefined. An action's value is yours and is never inspected, so undefined is a value you may legitimately give one; a selection carrying it is a row that offered actions and had one taken, which the equality test would misread as a row that offered none. The grid never writes the key it does not mean.
Once the promise settles, the terminal is yours. select does not settle until the dialog has restored the terminal and unmounted its renderer, on completion, cancellation, and failure alike, so the process you start next finds no raw mode, no input handler the grid installed, and nothing further written by it. Standard output is untouched throughout, so your own output and a launched process's are the only things on it. That is the one thing about the capability you cannot read off a type signature, and it is why the whole shape is worth writing out:
const plugin: Plugin = ({ command, context, registrations }) => {
command((namespace) => {
namespace.action(async () => {
const [grid] = registrations<Grid>("@fx/tx/grid");
if (!grid) throw new Error("grid capability missing");
const chosen = await grid.select({
message: "Pick a service",
headers: ["SERVICE", "STATE"],
rows: services.map((service) => ({
cells: [service.name, service.state],
value: service,
// Computed per row, so a retired service offers none while its
// neighbours offer two. An empty list is not a rejected request.
actions:
service.state === "retired"
? []
: [
{ label: "connect", value: "connect" as const },
{ label: "open logs", value: "logs" as const },
],
})),
});
// Nothing chosen at all: the reader cancelled.
if (chosen === undefined) return;
// Which of the two answers this is, is said by whether the key is
// there — not by what it holds. An action's value is your own, so
// `undefined` is a value you may legitimately give an action, and
// `chosen.action === undefined` would then read a row that offered
// actions and had one taken as a row that offered none.
if (!("action" in chosen)) {
context.stdout.write(`${chosen.value.name}\n`);
return;
}
// The dialog is gone and the terminal is back to what it was, so this
// process gets the user's keystrokes and leaves the terminal unbroken.
const executable = chosen.action === "logs" ? "journalctl" : "ssh";
Bun.spawnSync([executable, chosen.value.host], {
stdio: ["inherit", "inherit", "inherit"],
});
});
});
};Running, spawning, and supervising a process are the consumer's, not the grid's: it reports a chosen row and a chosen action and never runs, spawns, names, or interprets one. Returning to the rows after you have acted — the file-manager loop — is not offered; call select again if you want it.
Grid is the printed grid as a component, for a plugin that draws its own interface. A plugin running a render session of its own cannot print — the write lands beneath its session and the next frame overwrites it — so it renders Grid inside that session instead, with the React and Ink tx injected into it as dependencies.react and dependencies.ink and no other copy of either. It takes GridProps: a request, which is the printing request without its stream, and a width, the terminal columns it may lay out in. Those are the request and width every embeddable tx component takes, with the meanings Dialogs: Embeddable Components gives them; Grid answers no key, so it takes no height, isActive, onSubmit, or onCancel. A GridRequest you would otherwise print can be passed unchanged, stream and all, because the component neither reads nor writes that stream.
It hands your session exactly the lines print would write for the same request to a stream reporting width columns, every character of them included — a cell's own trailing spaces too — and every rule above about cells, tables, and flows holds for it. width is the only width a flow lays out against, and the terminal's is never read; a table keeps its natural width whatever width is, and how your layout treats one wider than that is yours. Whether your session then writes the trailing spaces of a line to the terminal is its renderer's business, not the grid's. Appearance is resolved through the theme capability for the standard error tx injected — the stream a dialog draws on — so colour is on for an embedded grid exactly when it is on for a dialog beside it. Grid writes to no stream, keeps no state between renders, and animates nothing: render it again with a different request or width and the next frame shows the change. A grid with nothing to draw — no rows, no empty message, and no summary — draws nothing and takes no rows. Every read of the capability yields the same Grid, so rendering it again with fresh props re-renders it rather than remounting it.
The contract types Grid as a function of its props returning unknown, so the published contract names no React type. Your plugin has React's types — @types/react is a dependency of @fx/tx — so cast the component where you hand it to createElement:
import type { Grid, GridProps } from "@fx/tx/grid";
import type { Plugin } from "@fx/tx/plugin";
import type { ReactNode } from "react";
const plugin: Plugin = ({ command, context, dependencies, registrations }) => {
const { react, ink } = dependencies;
command((namespace) => {
namespace.action(async () => {
const [grid] = registrations<Grid>("@fx/tx/grid");
if (!grid) throw new Error("grid capability missing");
// The contract's `unknown` narrowed where React's types are in scope.
const ServiceGrid = grid.Grid as (props: GridProps) => ReactNode;
function Dashboard({ width }: { readonly width: number }) {
return react.createElement(
ink.Box,
{ flexDirection: "column", width },
react.createElement(ink.Text, { bold: true }, "Services"),
react.createElement(ServiceGrid, {
request: {
layout: "flow",
rows: services.map((service) => [service.name]),
empty: "no services",
},
width,
}),
);
}
// Your session, on your streams: the grid draws inside it and owns
// none of them.
const session = ink.render(
react.createElement(Dashboard, { width: context.stdout.columns }),
{ stdout: context.stdout, stdin: context.stdin },
);
await session.waitUntilExit();
});
});
};SelectGrid is select as a component, for the same plugin. It takes SelectGridProps<T, A>: the GridSelectRequest you would pass to select as its request, and the width, height, isActive, optional keyHints, onSubmit, and onCancel every embeddable component that takes keys shares — the EmbeddedProps of Embed a dialog in your own interface, which the grid contract imports from @fx/tx/dialogs rather than restating, so they mean exactly what they mean for dialogs.Select. It draws its request as that embedded Select, given your width, height, isActive, and keyHints, so every rule above about selecting — the padded rows, the dropped variable and align, a row's actions as the column it opens, a row with no actions taken on its own — holds for it, and so does every rule that section states for an embedded Select: it is one-shot, it reads your callbacks on every call, it presents the request it was mounted with, and it answers keys only while it is active. onSubmit receives exactly the GridSelection select would resolve with, its action key absent where the row offered none, and onCancel is called where select would resolve undefined.
It reads the dialogs capability when it mounts, while your command runs, and fails that render — which your session's error handling sees like any other render failure — with an error naming the count where a tx is composed without exactly one dialogs provider, rather than falling back to anything. It writes to no stream and needs no interactive one, so the handover guarantee above is select's alone: a process you start after onSubmit inherits a terminal your session holds, and handing it over is yours. Every read of the capability yields the same SelectGrid. Cast it where you hand it to createElement, exactly as Grid:
import type { Grid, GridSelection, SelectGridProps } from "@fx/tx/grid";
import type { ReactNode } from "react";
// Inside your command action, with `grid`, `react`, and `ink` in hand.
const ServicePicker = grid.SelectGrid as (
props: SelectGridProps<Service, "connect" | "logs">,
) => ReactNode;
function Picker({ onPicked }: {
readonly onPicked: (chosen?: GridSelection<Service, "connect" | "logs">) => void;
}) {
const { columns, rows } = ink.useWindowSize();
return react.createElement(ServicePicker, {
request: {
message: "Pick a service",
headers: ["SERVICE", "STATE"],
rows: services.map((service) => ({
cells: [service.name, service.state],
value: service,
actions: [
{ label: "connect", value: "connect" as const },
{ label: "open logs", value: "logs" as const },
],
})),
},
width: columns,
height: rows - 1,
isActive: true,
onSubmit: (chosen) => onPicked(chosen),
onCancel: () => onPicked(undefined),
});
}Sorting, grouping, filtering, and paginating the supplied rows are out of scope, as are machine-readable output, borders and box drawing, spanning and wrapped cells, caller-specified widths, multi-row selection, in-place cell editing, column reordering, and value formatting of every kind — a duration, a timestamp, and a byte count are the consumer's to render into a string before it hands one over.
command(build) hands you your plugin's namespace: a command object named after your plugin's identity and already attached to the tree tx dispatches. Declaring commands, subcommands of any depth, arguments, options, and descriptions beneath it requires no parser dependency of your own. If you also want the parser itself — to build a detached command, share option definitions, or reuse its helpers — take it from dependencies.commander so you share the host's instance.
A few rules follow from the host owning the naming decision:
- A plugin that never calls
commandclaims no namespace. A plugin that calls it claims exactly one, named after its own identity — never after a parent marketplace or plugin. - An identity name that claims a namespace must be non-empty, must not contain whitespace, and must not begin with
-. Names that break those rules are rejected rather than reshaped. - Renaming the namespace or giving it an alias fails the plugin. Aliases on the commands you define beneath it are fine.
- Repeated
command(build)calls accumulate onto the same namespace instead of replacing it. - The builder must finish before it returns. An
asyncbuilder is rejected, because the rest of its work would land after tx has already committed what you staged. - A second plugin claiming a name that is already committed is rejected, and the diagnostic names both plugins.
Anything your plugin installs on a user's behalf can appear in tx update. Contribute an update participant during initialization; the driver knows nothing about what you own, and you never learn about anyone else's.
import type { Plugin, UpdateItem } from "@fx/tx/plugin";
const plugin: Plugin = ({ update }) => {
update({
gather: async () => [
{ name: "tools", current: "1.0.0", available: "1.1.0", detail: "two commits behind" },
{ name: "notes", current: "3.2.0" },
],
apply: async (item: UpdateItem) =>
item.available === undefined
? { applied: false }
: { applied: true, version: item.available },
});
};
export default plugin;gatherreports what you have. Leaveavailableout when there is nothing to apply, and setfailureon an item to report that one thing as unusable while your other items are still reported and applied. Gathering may contact a remote — that is what gathering is — but must change nothing installed, in a dry run or a real one.applyreturns a result or throws. Returningapplied: falsemeans you deliberately changed nothing and is not a failure; throwing is, and neither one stops the items beside it. It is called only for an in-scope item that reported anavailableversion and nofailure, and never at all on a dry run.- Version labels are opaque strings the driver never parses, compares, or orders. Deciding whether something is out of date is yours.
- Participants are staged with your commands and child definitions: a plugin that fails initialization contributes none. Contributing one claims no namespace, so a plugin may participate without defining a single command.
updaters()returns what is committed at the moment you call it, so read it inside a command action rather than during initialization. Participants come back in the host's FIFO commit order, which for the bundled plugins is the ordercli.tscomposes them in.
tx resolves the first argument only. The host owns exactly two root options — help, spelled --help or -h, and version, spelled --version or -V — and recognizes either one only in that position; tx --version extra behaves exactly like tx --version. Any other first argument selects a plugin namespace, and every argument after it — including options tx itself defines, and including help requests — is yours to interpret. tx notes --version gives --version to the notes plugin. tx reserves no top-level help word, so a plugin may be named help.
Root help lists every claimed namespace with the description its owner supplied, and per-command help is generated from your declarations, so no plugin hand-writes a usage string.
Every byte the host writes — root help, generated usage, version, and parser diagnostics — goes through the injected context streams, and dispatch itself never terminates the process: help, version, and usage rejections all resolve to an exit code returned to the composition root. Write your own output through the context streams rather than process.stdout or process.stderr, and let your actions return or throw instead of calling process.exit; plugins are trusted code, so nothing stops you from bypassing either, and both guarantees are yours to keep inside your own actions.
0— a command action that returns, a version request (--version,-V), or any help a user asked for:--helpand-hat any depth, and ahelpsubcommand inside your namespace if you keep the parser's default one. Requested help prints on standard output.1— everything else: an unrecognized first argument, arguments your parser rejects, a namespace invoked without one of its subcommands, or an action that throws. tx does not distinguish usage failures from runtime failures by exit code.
Usage that a user did not ask for — the help printed because your namespace needed a subcommand and got none — prints on standard error and counts as a failure, exactly as tx with no arguments prints root help on standard error and exits non-zero.
Commands, child definitions, generic registry entries, and update participants contributed during initialization form one atomic contribution; registration ends when initialization does. If loading, initialization, export validation, namespace validation, or collision detection fails, the plugin contributes nothing while healthy plugins can still dispatch. Failures are diagnosed on standard error and do not change the exit code of the command you ran, so a dispatched command keeps its own exit code — an action that succeeds still exits 0 — while a broken plugin is reported alongside it. Because a failed plugin claims nothing, invoking the namespace it would have owned is reported as an unknown command.
Bundled feature plugins live under plugins/<name>/, conventionally at plugins/<name>/index.ts. Only the root cli.ts composition root selects and orders defaults. Modules under src/ must remain feature-neutral and must not import or name bundled plugins; a bundled plugin's complete module graph must not import private core implementation under src/.
Use type-only imports from @fx/tx/plugin and from every capability contract the package publishes — @fx/tx/config, @fx/tx/dialogs, @fx/tx/theme, @fx/tx/theme-override, and @fx/tx/grid today — standard Node.js or Bun APIs, and plugin-owned modules. A published specifier is the one way a bundled plugin may name another bundled plugin's vocabulary: it carries types alone and is erased, so it shares no runtime module graph, while a relative path into another plugin's directory is rejected. None of them may be loaded at run time or imported from under src/. Plugin-owned nonliteral dynamic imports of configured entry paths are allowed.
Run bun run check to lint, type-check, test, and build. Add Bun tests for observable behavior and preserve 100% statement, function, and line coverage of production code.
For normative detail, see the plugin system specification and architecture specification. The completed external marketplace boundary change records the implementation history.