Genexy CLI
gnx) runs the Genexy IDE backend in your terminal. Today it brings the IDE's AI chat: the same agents, the free providers and your own OpenAI-compatible endpoints.Conversations, API keys and AI settings are shared with the IDE, so a chat started in the terminal can be continued in the IDE and the other way round.
There are three ways to chat:
| Command | What it is | Use it for |
|---|---|---|
gnx ai chat | Interactive chat with tabs, mouse and keyboard | Working with an agent in a terminal |
gnx ai repl | A loop of plain lines, no cursor keys or ANSI | Any terminal, serial lines, SSH, screen readers |
gnx ai ask "prompt" | One prompt, the answer on stdout, then it exits | Scripts, pipes and CI |
Install and check
Download Genexy CLI from the same Download page as Genexy IDE. No account and no sign-in
is needed. The CLI is a single gnx binary for Windows, macOS and Linux, and it does not need Genexy IDE to be
installed. Which architectures a release includes can differ from release to release; the Download page lists the
builds that are available for the current one.
Check the installed version with:
gnx --version
gnx version --jsonThe agents themselves are separate programs, as in the IDE. gnx ai agents ls shows which are installed and ready, and
gnx ai agents install <agent> runs the same installer the IDE uses.
In Genexy Shell inside the IDE, gnx is the built-in code
generator command (gnx create, gnx regenerate). The commands on this page belong to
the standalone Genexy CLI.
The project folder
gnx works in the current folder: that is the project the agents read and change, and whose conversations
gnx ai history lists. Point it elsewhere with -C:
gnx -C ~/projects/land-routing ai chatInteractive chat: gnx ai chat
gnx ai chat [prompt] opens a full-screen chat. The tabs of the last session are restored, and a prompt on the command
line is sent as the first message. The transcript reads like the IDE chat panel: answers, tool calls with their status,
collapsed reasoning, plans and permission requests with Always, Once and Deny. Click a tool call to see its
input and result.
The row under the composer holds the agent, the model, the agent mode (when the agent has modes) and Autopilot. Click a chip to change it; context use and the tokens spent are on the right.
| Key | Action |
|---|---|
| Enter | Send |
| Shift+Enter, Alt+Enter, Ctrl+J | New line |
| Esc | Stop the running turn |
a, o, d (with an empty composer) | Answer a permission: always, once, deny |
/ | The agent’s own slash commands |
| Tab | Next agent mode |
| Ctrl+T, Ctrl+O | Show reasoning, expand the last tool call |
| Ctrl+N, Ctrl+W, Alt+1..9 | New tab, close tab, switch tab |
| Up, Down | Earlier prompts |
| Ctrl+K | Command menu |
| F1, F2, F3 (Ctrl+G toggles the log) | Chat, AI Settings, IDE log |
| Ctrl+C twice, Ctrl+D | Quit |
The composer also takes the REPL commands: :history opens a saved conversation, :attach <path> attaches a file,
:copy copies the last answer, :rename renames the tab.
To select text with the mouse, hold Shift (Option on macOS) while dragging. The interactive chat needs a terminal with
ANSI support; where there is none, gnx says so and points you to gnx ai repl.
AI Settings
F2 opens the AI settings: every agent with its install and login state, the free providers, your custom endpoints and the behaviour settings. The details of the selected entry are on the right, with its actions as buttons; the letter in brackets runs one from the keyboard.
F3 shows the IDE log of the backend, with level filters, search and follow mode.
Line-based chat: gnx ai repl
gnx ai repl [prompt] is the same chat as plain lines. Your prompt is user>; answers start with agent> and tool calls
with tool>. Nothing moves the cursor, so it works in any terminal, in an SSH session or over a serial line, and with
screen readers.
- A permission request is answered with
1(always),2(once) or3(deny). - A message between two lines of
"""spans several lines. - Ctrl+C stops the running turn; on an empty prompt it asks you to press it again, or type
:quit. - Lines starting with
:are commands:
| Command | Action |
|---|---|
:new [agent], :tabs, :tab <n>, :close [n] | Open, list, switch and close tabs |
:history, :resume <n|id> | Saved conversations; open one in a new tab |
:agent, :model, :mode, :options | Change the agent, model, mode or agent options |
:autopilot on|off | Approve tool calls without asking |
:stop | Stop the running turn |
:attach <path>, :attachments, :detach | Attach files to the next message |
:settings, :keys [agent], :usekey <id|none>, :login [agent], :usage | Agents, keys and plan use |
:logs [n] | Follow the IDE log; Enter goes back to the chat |
:help, :quit | List the commands, exit |
One answer: gnx ai ask
gnx ai ask "prompt" sends one prompt, prints the answer and exits. The answer goes to stdout, tool calls and the usage
line to stderr, so a redirect or a pipe receives only the answer. Piped input is attached to the prompt as context:
git diff | gnx ai ask "review this change"
gnx ai ask --agent free-llm7 "explain this error" < build.log > answer.mdIf the agent asks for a permission, ask asks you on the terminal. Without a terminal (in a pipe or in CI) it declines
and exits with code 4, unless --autopilot or --yes allows every tool call. --timeout <seconds> stops a turn that
takes too long, and --json prints the answer, the tool calls, the plan and the usage as one JSON object.
| Exit code | Meaning |
|---|---|
| 0 | The answer is complete |
| 1 | The turn failed |
| 2 | Wrong command line (unknown command, flag or argument) |
| 3 | The agent is not ready: not installed or not logged in |
| 4 | A permission was declined |
| 5 | --timeout was reached |
| 130 | Interrupted with Ctrl+C |
The conversation is saved like any other; continue it with gnx ai chat --continue or in the IDE.
Options for chat, repl and ask
| Option | Effect |
|---|---|
-a, --agent <id> | kiro, claude, codex, copilot, cursor, a free provider such as free-llm7, or a custom endpoint id |
-m, --model <id> | A model from gnx ai models ls |
--mode <id> | The agent mode, if the agent has modes (for example code or plan) |
--autopilot, --no-autopilot | Approve every tool call, or ask even when ai.autopilotDefault is on |
-c, --continue | Continue the newest conversation of the project |
-r, --conversation <id> | Resume a conversation from gnx ai history ls |
-f, --file <path> | Attach a file to the first message; repeat for more files |
Without --agent, a new chat uses ai.defaultAgent.
Agents and API keys
gnx ai agents ls lists the agents the IDE works with and whether each is ready:
ID NAME VERSION LOGGED IN API KEY STATUS
kiro Kiro 2.31.0 yes - ready
claude Claude Code 2.1.251 n/a (key) yes ready
codex OpenAI Codex 0.153.4 yes - ready
copilot GitHub Copilot 1.0.103 yes - ready
cursor Cursor 2026.09.08-6caf4ff yes - ready
opencode OpenCode 1.14.2 n/a (key) - ready
cline Cline 2.6.0 n/a (key) - readyAn agent is ready when it is installed and either logged in or has an active API key. Claude Code has no login and
always needs a key. OpenCode and Cline keep their own credentials: they are ready once installed, and you connect
their model providers with opencode auth login or cline auth, or add a key with gnx ai agents keys add.
| Command | Action |
|---|---|
gnx ai agents install <agent> | Install the agent CLI |
gnx ai agents login <agent>, logout | Run the agent’s own login (opens a browser), or log out |
gnx ai agents whoami <agent> | The account the agent is logged in with |
gnx ai agents usage [agent] | Plan use: Kiro credits, Codex rate-limit windows |
gnx ai agents keys add <agent> [--name n] | Store an API key and activate it |
gnx ai agents keys ls, use, rename, rm | List, activate, rename and remove keys |
The key is typed without echo, or read from stdin, so it does not end up in your shell history:
echo "$ANTHROPIC_API_KEY" | gnx ai agents keys add claude --name workOn a machine without a browser, an API key is the way to make an agent ready.
Providers and models
Besides the agents, the chat can talk directly to OpenAI-compatible endpoints: the built-in free providers (LLM7, Kilo, OVHcloud), which need no key and cannot be changed, and your own, such as Ollama, LM Studio, vLLM, OpenRouter or a company gateway.
gnx ai providers add Ollama http://localhost:11434/v1 --no-key
gnx ai providers add OpenRouter https://openrouter.ai/api/v1
gnx ai chat --agent <provider id>gnx ai providers ls lists them with their ids, test checks the connection, models lists what a provider serves,
and edit and rm change or delete a custom endpoint. gnx ai providers limits set with --max-tool-calls and
--max-rounds bounds the agent loop of these providers; 0 means unlimited.
gnx ai models ls [--agent <id>] lists the models of the ready agents and providers. Agents can offer more models once
a session runs; the model chip in gnx ai chat shows those too.
Settings and history
The AI settings are stored in ~/.genexy/preferences.json, the same file the IDE’s Settings › AI uses:
| Setting | Default | Meaning |
|---|---|---|
ai.defaultAgent | last | Agent for a new chat: last, kiro, claude, codex, copilot, cursor |
ai.autopilotDefault | false | New chats approve every tool call |
ai.alwaysAllowedTools | [] | Tools approved without asking, for example read,grep |
ai.usageWarningPercent | 80 | Warn at this share of a plan; 0 turns the warning off |
Read and change them with gnx ai config ls, get <key>, set <key> <value> and unset <key>.
Conversations are saved in ~/.genexy/chats, per project, like the IDE saves them. gnx ai history ls lists those of
the project, show <id> prints one and rm <id>... deletes them, also from the IDE’s history. Resume one with
gnx ai chat -r <id> or gnx ai repl -r <id>.
Every listing command takes --json for scripts.
The CLI runs the agents on your machine with the same rights as in the IDE: they can read and change files in the
project folder and, after your approval or with Autopilot, run commands. Use --autopilot and --yes in scripts only
for projects you can restore, and review the result with Git afterwards.