GeneXus.CLI.any 2.0.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 (per-KB resolution)

The MCP used to operate on a KB is dictated by the KB itself, not by a global env var — which matters when several GeneXus versions are installed. 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 it (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 MCP found under the KB's installation path.

GX_MCP_SERVER_EXE is used only as the default when creating a new KB and no server is running (then PATH, then next to the gx binary). Disable any auto-start with --no-autostart or GX_MCP_NO_AUTOSTART=1.

Creating GeneXus 18 KBs (GXV18_INSTALLATION_DIRECTORY)

create-knowledge-base can create a GeneXus 18 KB by delegating to a local GX18 installation. The installation is designated by the GXV18_INSTALLATION_DIRECTORY environment variable — when it is not defined, the KB is created with the current GeneXus and nothing changes.

When the variable is defined, before calling the server the CLI resolves the installation to use:

• Variable has 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).
• Variable is defined but empty → interactive runs ask for the path and persist it at user scope (Windows); leave it empty to create a current-version KB.
• 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 variable as-is. With an empty variable there is no value to use, so this answers "create a current-version KB", warned with [GNC0036] — it is the one way of answering that does not produce a GX18 KB.
• --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] (variable with a value) or [GNC0038] (variable empty), 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.

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
• 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.