GeneXus.CLI.win-arm64 2.1.0

GeneXus.CLI (gx)

Command-line client for the GeneXus MCP server. gx exposes the server's tools (Knowledge Base operations, builds, exports, …) as terminal subcommands — suitable for use from CI, shell scripts, or AI coding agents.

Installation

dotnet tool install --global GeneXus.CLI

No need to pick a platform-specific package — the .NET tool resolver automatically selects the right build for your runtime. Native-AOT (self-contained, no separate .NET runtime needed): win-x64, win-arm64, linux-x64, osx-arm64. Any other runtime (e.g. linux-arm64) falls back to a framework-dependent build, which requires a .NET runtime already installed. After install, the executable is on PATH as gx.

Prerequisites

• .NET 10 SDK — required to install the tool. The automatic per-platform resolution relies on .NET 10's RID-specific dotnet tool support.
• A running GeneXus MCP server reachable at http://127.0.0.1:1989/mcp by default. Override with --server <url> or the GX_MCP_SERVER environment variable.

Which MCP server is used

gx reads the KB's version + installation path from its text mirror (src/#preferences/<kb>.kb.gx) or .gxw (under an explicit --directory if given, else the current directory) and compares the version (major.minor) with the running MCP's GET /version:

• compatible (same major.minor, or a v18 KB that any v19+ MCP handles) → uses the running server;
• incompatible → refuses without touching the running server and reports [GNC0030] so you can stop it and retry, or pass --server for the right one. To upgrade/convert an older KB with a newer GeneXus, re-run with --allow-version-mismatch: gx opens it with the running MCP and warns ([GNC0052]) instead of refusing;
• none running → auto-starts the configured default server: GX_MCP_SERVER_EXE, then the first GeneXus.PIA.McpServer on PATH, then next to the gx binary (what the GeneXus for Agents setup installs). One MCP drives every KB, v18 KBs included, so a KB last opened by a GeneXus 18 install starts that same default server. The started server is then checked against the KB like a running one ([GNC0030] / --allow-version-mismatch). Only when no default is configured does gx fall back to the MCP under the KB's own installation path (several GeneXus Next installs side by side); [GNC0031] means neither exists.

Disable any auto-start with --no-autostart or GX_MCP_NO_AUTOSTART=1.

Creating GeneXus 18 KBs (GXV18_INSTALLATION_DIRECTORY)

create-knowledge-base creates a GeneXus 18 KB by delegating to a local GX18 installation — every new KB targets GX18, there is no current-version fallback. The installation is designated by the GXV18_INSTALLATION_DIRECTORY environment variable, resolved across Process, User, and Machine scope (Windows; non-Windows has Process scope only) — the first non-blank value wins, and a value blank at every scope is treated the same as the variable never being set.

Before calling the server the CLI resolves the installation to use:

• Configured with a value → interactive runs show Creating a GeneXus 18 KB with the installation at: <path> and wait: press Enter to confirm, or type a different installation path to use it for this run only (the variable is never rewritten).
• Not configured → interactive runs ask for the installation path and persist it at user scope (Windows).
• Every resolved path is validated up front (Genexus.Tasks.targets must exist there); an invalid path is refused with [GNC0035]. At either interactive prompt the first invalid path is reported and asked again once, so a typo costs a retry rather than the run.

Two options answer the question up front, and are the way to answer it without interaction:

• --yes / -y — use the configured variable as-is. With nothing configured there is no value to take, so this errors with [GNC0038].
• --v18-installation-directory <path> — use <path> for this run, no prompt, variable untouched.

Runs that cannot prompt — redirected stdin (typically an agent driving the CLI) or --json — do not assume an answer: they are refused with [GNC0037] (configured with a value) or [GNC0038] (not configured), both naming the two options above. A console prompt never reaches whoever is driving such a run, so the command stops instead of creating a KB against an installation nobody confirmed. The expected loop for an agent is: run → read the error → ask the user which installation to use → re-run with --yes or --v18-installation-directory <path>.

The same refusal applies when the prompt is shown but stdin ends without an answer (Ctrl+Z on Windows, Ctrl+D elsewhere): pressing Enter confirms the configured installation, whereas ending stdin confirms nothing and is reported as [GNC0037] / [GNC0038] rather than treated as a yes.

The resolved directory travels in the tool request, so it applies even when the MCP server process was started without the variable.

Usage

Subcommands are derived at runtime from the MCP server's tools/list response — they reflect whatever tool set your server exposes today.

gx --help                # list available subcommands
gx list-tools            # short table: name + description
gx list-tools --json     # full JSON schemas (machine-readable)
gx list-tools --filter gxserver_  # only tools whose name starts with a prefix
gx <subcommand> --help   # options for a specific subcommand
gx --refresh-tools ...   # bypass the local schema cache

Tool names are kebab-case (e.g. open-knowledge-base, build-all, export-kb-to-text). The exact set is server-configurable; run gx list-tools against your target server for the live catalog.

Opening a KB on a version

gx open-knowledge-base --knowledge-base-name "Sales"                          # the last version used in the KB (IDE or MCP), else the trunk
gx open-knowledge-base --knowledge-base-name "Sales" --version-name "V2"      # that version, recorded as the last used

The result names the version the KB opened on and why. Frozen versions are never opened: the command fails (✗, exit 1) and lists the versions that can be. On a KB that is already open --version-name does not switch the version; use gx set-active-kb-version.

Opening a KB with no text (KB-text mirror on hold)

The MCP server keeps a text copy of the KB on disk (the KB-text mirror, one git branch per KB version). When the directory has no text for the active version yet, starting the mirror would export every object, which takes a long time on a large KB. open-knowledge-base then opens the KB but puts the mirror on hold — the command succeeds and prints the options instead of exporting:

gx open-knowledge-base --knowledge-base-name "Sales" --confirm-full-export   # (a) export this version, in the background
gx list-kb-versions                                                           # (b) or pick another version…
gx set-active-kb-version --version-name "<version>"                           #     …a version with no text is held in turn
gx close-knowledge-base --directory "<kb dir>"                                # (c) or close it and open another KB

While the KB is on hold, commands that change it — export-kb-to-text included — are refused with [GNC0017] and the same options; reads, the commands above, get-kb-text-mirror-status, validate-kb-text-files, get-kb-property, export-knowledge-manager, KB creation, the GeneXus Server reads (gxserver-status, gxserver-list-server-kbs, gxserver-pending-changes, gxserver-login, gxserver-create-kb-from-server), search-modules and the session commands (login, logout, switch-organization, auth-status) keep working. Once confirmed, a branch regeneration keeps those commands refused (and set-active-kb-version too) until it ends. set-active-kb-version itself takes --confirm-full-export when the switch has to regenerate all of the target version's text.

Creating a KB (create-knowledge-base, gxserver-create-kb-from-server) is the request for its text. With the mirror enabled the mirror owns that export: the command returns right away and reports what the mirror is doing — exporting in the background (catchingUp / fullExportInProgress), running without exporting (its catch-up already ended, or did not run, e.g. because the directory is on another version's branch), or onHold with no objects exported and the options to put to the user (a checkout with useCurrentVersion still lands there, until the server confirms its export too). Check gx get-kb-text-mirror-status before relying on the text under src/. Without a mirror the command exports the objects itself before returning. Either way, do not run export-kb-to-text afterwards.

gx get-kb-text-mirror-status reports the mirror's state — inactive, running, catchingUp, onHold or fullExportInProgress — with the server's explanation (detail) and the start time of a running full export (exportStartedUtc).

Output modes

Mutually-exclusive flags:

The last line of every run is a structured RESULT: summary (in quiet/verbose) or a kind:result JSON entry (in --json) — that's the contract scripts should parse to determine the outcome.

Exit codes

• 0 — success
• 1 — failure (including a command the server refused, e.g. [GNC0017] while the KB-text mirror is on hold)
• 130 — interrupted (Ctrl+C)

License & usage

The gx CLI is licensed under Apache 2.0. It is a client for the GeneXus MCP server, which is a separate product distributed under its own license and terms — installing this CLI does not grant any rights to the GeneXus server or product, and obtaining and using them requires a valid GeneXus license. Third-party components bundled in this package (System.CommandLine and, in the Native AOT flavors, the statically linked .NET runtime — both MIT-licensed) are covered by their own licenses, reproduced in THIRD-PARTY-NOTICES.txt at the root of the package.