EvoX CLI Quickstart

Installation and getting started with EvoX in your terminal.

This page covers the EvoX CLI produced by the EvoMap/evox repository: the evox command that runs in a terminal. It is not the npm package @evomap/evolver, which is a separate Evolver CLI with different installation, configuration paths, and command names.

1. What is EvoX CLI?

EvoX CLI is an AI coding assistant that runs in a terminal. It can read project files, run commands, modify code, and support an interactive TUI, one-shot tasks, session continuation, Gateway, and extensions.

2. Get running in five minutes

Step 1: Install

macOS

Run this in Terminal:

curl -fsSL https://evomap.ai/evox/install.sh | EVOX_CHANNEL=beta sh

Linux

Before installation, make sure these are available:

• curl or wget
• jq or python3
• tar
• install
• OpenSSL 3+ with support for pkeyutl -rawin

Then run:

curl -fsSL https://evomap.ai/evox/install.sh | EVOX_CHANNEL=beta sh

The online installer detects Linux and switches to the Linux release source automatically.

Windows

Open PowerShell and run:

$env:EVOX_CHANNEL = 'beta'
irm https://evomap.ai/evox/install.ps1 | iex

The installer places EvoX CLI at:

%LOCALAPPDATA%\EvoX\bin\evox.exe

The script adds that directory to the current user's PATH. Close and reopen PowerShell before continuing.

Step 2: Verify the command

evox --version
evox --help

When the installation is ready, evox --version returns version information similar to:

evox v1.1.0-beta.26 (...)

The exact version changes with each release and does not need to match the example.

If macOS or Linux reports evox: command not found, run this in the current shell:

export PATH="$HOME/.local/bin:$PATH"

Then add the same line to ~/.zshrc, ~/.bashrc, or the shell configuration used by your team so the path is retained in future sessions.

Step 3: Configure a model

For the first run, configure only the model. Do not enter Gateway or advanced self-evolution settings yet:

evox configure quick

Follow the wizard to:

1. Choose a model provider.
2. Enter the required credential.
3. Choose the default model.
4. Review the final confirmation screen before writing the configuration.

Do not send API keys, tokens, or other credentials in chat, issues, screenshots, or log attachments. Avoid putting secrets directly in a --api-key argument because they can be recorded in shell history.

View the actual configuration file location:

evox config path

View a redacted configuration summary:

evox config list

Step 4: Run a health check

evox doctor

ok means the check passed. skip usually means an optional capability is not enabled. Read any warn message; it does not necessarily mean that every workflow is blocked.

To show only warnings and failures:

evox doctor --quiet

Step 5: Run a first read-only task in a project

First enter the project directory:

cd /path/to/your/project

In Windows PowerShell, you can use:

Set-Location 'C:\path\to\your\project'

For the first check, use read-only tools:

evox --tools read,grep,find,ls -p "Read this repository and return: 1) the main language and framework; 2) the entry point; 3) how to run tests. Do not modify files."

If EvoX returns the project structure and test instructions, installation, model configuration, network access, and project reading are all working together.

If you see PermissionDenied, prompt WAL, or an error writing to the agent directory, do not keep retrying blindly. Run evox config path, check whether that directory and its parents are writable by the current user, and send a redacted error to the project contact.

3. Everyday use

Interactive terminal UI

evox tui

The TUI supports ongoing conversations, a model selector, and session history. Before asking EvoX to modify files or run commands, confirm that the current directory is the intended project.

Run a one-shot task

evox -p "Summarize this repository and identify the safest next implementation step."

The CLI exits after the task finishes, which is useful for scripts, CI preflight checks, and simple inspections.

Ask about an attached file

evox -p @README.md "Summarize the setup steps and list anything missing."

Continue the previous session

evox --continue -p "Continue from the previous result and propose tests."

Choose a model

evox --model <provider>/<model> -p "Review this change."

Replace <provider>/<model> with a real model identifier allowed by your team and backed by configured credentials.

4. Common commands

5. Optional: Start the local Gateway

Gateway provides inbound connection support and a local browser-based management and chat interface. Skip this section if you only need the terminal coding assistant.

First configure Channels and Gateway:

evox configure channels

Start it and check its status:

evox gateway start
evox gateway status

Default local address:

http://127.0.0.1:9700/

Stop Gateway with:

evox gateway stop

Gateway binds to the local loopback address by default. Do not expose it to the public internet until authentication and network boundaries have been reviewed.

6. Current-version limitations

evox start is not the main path yet

In the verified Beta build, the background daemon bridge is not connected yet. Running evox start reports that no background session service is available.

Use one of these instead:

evox tui

or:

evox -p "<prompt>"

evox gateway start is a separate entry point and is not equivalent to evox start.

Remote package management is not available yet

The current build still reports evox package as unavailable. Do not make it a required Partner onboarding step. For local extension development, use the separate evox ext ... workflow when appropriate.

7. Updates and channel switching

After installing with the scripts above, the safest update path is to run the same installation command again. The installer rereads the channel manifest, downloads the current build, and verifies its SHA-256 checksum.

Beta update:

curl -fsSL https://evomap.ai/evox/install.sh | EVOX_CHANNEL=beta sh

Windows:

$env:EVOX_CHANNEL = 'beta'
irm https://evomap.ai/evox/install.ps1 | iex

Do not make evox self-update a required step for script-installed builds. The current build may not recognize that installation mode and may ask you to use the matching channel installer again.

Channel status (verified September 24, 2026):

8. Uninstall

The current CLI help does not expose a dedicated uninstall subcommand.

• On macOS/Linux, the executable is normally at ~/.local/bin/evox.
• On Windows, the executable is normally at %LOCALAPPDATA%\EvoX\bin\evox.exe.
• User configuration, sessions, and logs are usually near the directory reported by evox config path.

Removing only the executable does not remove user data. Unless you have a backup and an explicit reason for a full cleanup, do not delete the entire EvoX data directory.

9. Troubleshooting

evox is not found after installation

1. Windows: close and reopen PowerShell.
2. macOS/Linux: confirm that ~/.local/bin is in PATH.
3. Run evox --version again.

The CLI reports that no model credential is configured

Run:

evox configure quick

Confirm that the selected provider matches the credential. Do not paste the credential into a public message.

The CLI starts but the task fails

Collect these outputs in order:

evox --version
evox doctor --quiet
evox logs --list
evox logs --errors -n 100

If evox logs --errors reports that there is no matching log file, provide the result of evox logs --list first. Check every output for keys, tokens, private repository URLs, usernames, or sensitive local paths and redact them before sharing with the project contact.

Linux installation fails

Check these items first:

1. The beta channel is selected.
2. jq or python3 is installed.
3. OpenSSL is version 3+ and supports pkeyutl -rawin.
4. The network can reach evomap.ai and res.evomap.ai.

10. What to include when reporting an issue

• Operating system and CPU architecture.
• Output from evox --version.
• The selected channel: beta or stable.
• The command that was run and the complete error text.
• Redacted output from evox doctor --quiet.
• When needed, redacted output from evox logs --errors -n 100.
• Whether the issue occurred during installation, configuration, TUI use, a one-shot task, or Gateway.

Never include API keys, tokens, passwords, authorization codes, or an unredacted configuration file.

EvoX Docs · Overview · Available on