FAQ

FAQ

🌍 English · Polski · Français · Deutsch · 中文

Frequently asked questions about ECLI.

General

What is ECLI?

ECLI (Editor CLI) is a terminal-native IDE built in Python. It combines a curses-based editor with AI, Git, LSP, Tree-sitter syntax highlighting, and a plugin system. It's designed for developers who prefer working entirely in the terminal.

Why another terminal editor? Vim/Emacs/Helix/nano exist.

ECLI's positioning:

• Vim/Neovim — extremely powerful but steep learning curve and configuration burden.
• Emacs — Lisp-based, extreme flexibility, but high overhead.
• nano — minimalist, lacks IDE features.
• Helix — modern, modal, but no AI panel and Rust-based extensibility.
• ECLI — IDE-style ergonomics (familiar Ctrl+S/Ctrl+O bindings), AI built in, Python plugins, single TOML config. Aimed at "VS Code in a terminal" rather than "Vim with batteries".

If Vim/Helix fit your workflow, stick with them. ECLI exists for people who want IDE conventions in a TUI.

Is ECLI free?

Yes — Apache 2.0 licensed. Free for any use including commercial.

Does it work over SSH?

Yes. ECLI is a terminal app. It runs anywhere ssh + a working terminal does. Performance is excellent over slow links because it sends only text deltas, not framebuffers.

Will it eat my files?

No. ECLI:

• Saves atomically (writes to temp file, then renames).
• Prompts before quitting with unsaved changes (Ctrl+Q).
• Keeps Git integration read-only by default — destructive operations (force push, reset hard) require explicit confirmation.

If something breaks: open an issue with the contents of editor.log.

---

Installation

Which install method should I use?

• Native package if you want a standalone binary, no Python on the system: pick .deb / .rpm / .pkg / .dmg / .exe.
• PyPI if you already have Python 3.11+: pip install ecli-editor.
• From source if you want to contribute or use unreleased features.

Do I need Python installed?

• Native packages: no. They bundle Python via PyInstaller.
• PyPI: yes, 3.11+.

Why is the binary so big (~50 MB)?

PyInstaller bundles Python runtime + every dependency into a single file. This is the price for a no-deps install. The PyPI wheel is much smaller (~1 MB) because it relies on your Python install.

Does ECLI work on Apple Silicon?

Yes. The macOS DMG is Universal2 (arm64 + x86_64). No Rosetta required on M1/M2/M3/M4.

Does ECLI work on Windows ARM?

Not yet. The Windows release is x86_64 only. ARM Windows support is on the roadmap.

Does ECLI work on 32-bit systems?

No. Modern Python and most dependencies require 64-bit.

---

Features

How do I configure the AI panel?

See AI Setup. Short version: edit ~/.config/ecli/config.toml and add your API key under [ai.<provider>].

Can I use ECLI without AI?

Yes. Set default_provider = "none" in config, or just don't open the panel.

What languages does syntax highlighting support?

Tree-sitter grammars for 70+ languages including Python, JavaScript, TypeScript, Go, Rust, C, C++, Java, Ruby, PHP, HTML, CSS, JSON, YAML, TOML, Markdown, SQL, Bash, PowerShell, and more.

Does LSP work?

Yes, ECLI implements the Language Server Protocol client side. Install language servers per language:

# Python
pip install python-lsp-server

# Rust
rustup component add rust-analyzer

# Go
go install golang.org/x/tools/gopls@latest

# TypeScript / JavaScript
npm install -g typescript-language-server

Configure in ~/.config/ecli/config.toml:

[lsp]
enabled = true

[lsp.python]
command = "pylsp"

[lsp.rust]
command = "rust-analyzer"

Does Git integration require git installed?

Yes. ECLI shells out to the git binary. Install via your distro.

Can I use ECLI in tmux?

Yes. ECLI works inside tmux with no special config. Make sure your tmux is set for 256-color or truecolor:

# ~/.tmux.conf
set -g default-terminal "tmux-256color"
set -as terminal-features ",xterm-256color:RGB"

Mouse support?

Yes, ECLI supports mouse selection, scrolling, and panel resizing in terminals that support mouse events (most modern ones).

Multi-cursor?

Not in 0.1.x. Planned for v0.2.

---

Performance

How big a file can ECLI open?

Comfortably tested up to ~50 MB. Beyond that, Tree-sitter parsing and LSP can slow down. For multi-GB log files, use less or a dedicated tool.

Why does the AI panel feel slow?

It depends on the provider:

• Anthropic / OpenAI — network round-trip (200-2000 ms typical).
• Ollama — local model size; 7B models respond in 1-5 seconds.

If responses are way slower than expected, see Troubleshooting › AI.

---

Configuration and customization

Where's the config file?

Platform	Path
Linux / FreeBSD	~/.config/ecli/config.toml
macOS	~/Library/Application Support/ecli/config.toml
Windows	%APPDATA%\ecli\config.toml

How do I reset to defaults?

Delete the config file. ECLI regenerates it on next launch.

Can I have a config per project?

Yes. Drop a .ecli.toml in the project root. It overrides the user config for that project. See Configuration › Per-project config.

Can I write plugins?

Yes, in Python. See Themes & Customization › Plugins.

---

Troubleshooting

Most common problems

• "ecli: command not found" → Troubleshooting
• macOS Gatekeeper blocks first launch → Installation › macOS
• Windows SmartScreen warning → Installation › Windows
• Garbled colors → Themes › Color palette notes
• AI "API key not configured" → AI Setup

Full list: Troubleshooting.

How do I get help?

In order:

1. Search GitHub Discussions
2. Search GitHub Issues (including closed)
3. Open a new issue with editor.log and your config (redact API keys)

---

Project

How do I contribute?

See Contributing. PRs welcome for bug fixes, language definitions, themes, plugins, docs.

Is there a roadmap?

Yes: Roadmap.

Why "ECLI"?

"Editor CLI" — pronounced "echo lee". The logo is a stylized E evoking both the editor and command-line prompts.

Who builds ECLI?

Maintained by Siergej Sobolewski. Contributions welcome.

How are releases versioned?

Semantic versioning: MAJOR.MINOR.PATCH. Currently in 0.x — expect occasional breaking config changes between minor versions until 1.0.