ecli Logo

Terminal-First Engineering Operations Workbench
Panel-driven editor, diagnostics surface, and service foundation for controlled operational workflows

PyPI Version Python Versions Release License Website

Linux macOS FreeBSD Windows

ECLI (Editor CLI) is a terminal-first engineering operations workbench. It combines a curses-based editor with right-side workflow panels and a typed service foundation for configuration, project discovery, command-plan previews, policy checks, audit logging, privileged-action refusal paths, and read-only system diagnostics.

The v0.2.4 release layers the Extensions Foundation, extension-backed TextMate rendering, the F4 Diagnostics/Linter architecture, and release gate hardening on top of the Services Foundation and v0.2.3 Panel Console Stabilization work. It keeps the existing editor and service-panel safety model intact while adding curated extension assets, deterministic syntax/theme adapters, F4 linter provisioning contracts, Linux official evidence drift checks, and separated release validation gates.

• 🧠 AI Code Assistant - F7 panel for code-generation and refactoring help when a user-provided API key is configured

• 🩺 System Doctor - F8 read-only diagnostics panel with structured findings and preview-only remediation plans

• 🧭 Services Panel - right-side visibility into the Phase 1 service composition root

• 📋 Command Plan Preview - draft plans from eligible diagnostics, exportable as JSON or Markdown without execution

• 📂 File Manager - F10 project navigation and file preview workflow

• 🌱 Git Panel - F9 repository panel for existing Git workflows

• 🔎 Diagnostics/Lint - F4 diagnostics and lint panel

• ❓ Help - F1 help panel with current keybindings

• 🌈 Syntax Highlighting - terminal highlighting for common source formats

• 📝 LSP Integration - Language Server Protocol support where configured

• 🔄 Cross-Platform Packaging - PyPI, Linux, FreeBSD, macOS, and Windows release artifacts

Download and install a pre-compiled package for your platform when available:

# Debian/Ubuntu
sudo apt install ./ecli_<version>_linux_x86_64.deb
# Fedora/RHEL/Rocky/Alma
sudo dnf install ./ecli_<version>_linux_x86_64.rpm
# SUSE/openSUSE
sudo zypper install ./ecli_<version>_opensuse_x86_64.rpm
# Arch Linux
sudo pacman -U ./ecli_<version>_arch_x86_64.pkg.tar.zst
# Slackware
sudo installpkg ecli_<version>_slackware_x86_64.txz
# NixOS / Nix
nix run .
# AppImage
chmod +x ./ecli_<version>_linux_x86_64.AppImage
./ecli_<version>_linux_x86_64.AppImage
# Windows (PowerShell)
.\ecli_<version>_win_x86_64_setup.exe
# Portable alternative: .\ecli_<version>_win_x86_64.exe
# See docs/install/windows.md for checksum verification and SmartScreen notes.
# macOS
open ecli_<version>_macos_universal2.dmg
# First launch is blocked by Gatekeeper; see docs/install/macos.md
# for the one-time "Open Anyway" or xattr workaround.

Release artifacts are published at GitHub Releases when available.

Official releases upload exactly 21 ECLI-owned physical GitHub Release assets, one per canonical artifact contract entry. GitHub may display Assets 23 because it adds generated Source code (zip) and Source code (tar.gz) archives automatically; those source archives are not part of the canonical 21 artifact contract entries. SHA256 sidecars are CI/release verification evidence under .checksums/, not uploaded as separate GitHub Release assets.

ECLI Full artifacts are the supported user path for complete F4 diagnostics. The Full installer must detect the operating system and artifact context, check already-installed required linters/toolchains first, install or bundle missing required tools with the correct OS/artifact-specific mechanism, and verify executability plus versions. A missing required linter after Full install is a packaging defect or damaged-install condition, not normal user setup.

PyPI, pipx, and source checkouts are minimal/developer paths for non-Python linters because Python package metadata cannot reliably provision Node, Rust, Go, Zig, Java, and system binaries. Manual linter installation is reserved for developer checkouts, PyPI/source/minimal installs, repair, and advanced administration. See F4 Linter Manual Installation Reference.

Debian 13 testing validated a mixed provisioning strategy for Full artifacts: npm with a custom ECLI-managed prefix, dedicated Python virtual environments, prebuilt binaries, cargo install, JAR shims, verified upstream release downloads, and rustup component add clippy.

# Clone the repository
git clone https://github.com/SSobol77/ecli.git
cd ecli
# Install dependencies and run
make install
make run

sudo apt update
sudo apt install pipx
pipx ensurepath
pipx install ecli-editor
ecli

The Python distribution name is ecli-editor; the import package remains ecli, and the installed CLI command remains ecli.

Optional Linux desktop launcher and icon integration after pipx or pip installation:

ecli-install-desktop-entry

This installs a user-level launcher at ~/.local/share/applications/ecli.desktop and the icon at ~/.local/share/icons/hicolor/256x256/apps/ecli.png. It does not require sudo and is safe to run again.

For detailed platform-specific installation instructions, system dependencies, and troubleshooting, see the Installation Guide.

These dependencies are required for terminal UI, clipboard integration, YAML acceleration, and UTF-8 support.

Debian/Ubuntu:

sudo apt update && sudo apt install \
 libncurses6 libncursesw6 libtinfo6 \
 libncurses-dev libncursesw5-dev \
 ncurses-bin ncurses-term \
 libyaml-dev xclip xsel

Fedora/RHEL/Rocky/Alma:

sudo dnf install ncurses ncurses-devel libyaml-devel xclip xsel

SUSE/openSUSE runtime:

sudo zypper install ncurses6 libyaml-0-2 xclip xsel

For local RPM/package builds on SUSE/openSUSE:

sudo zypper install python3 python3-pip python3-devel gcc make rpm-build

Arch Linux:

sudo pacman -S ncurses libyaml xclip xsel

Slackware:

Install these from the official Slackware series or SlackBuilds according to your Slackware release:

ncurses
libyaml
xclip or xsel, if available

For .txz package builds, the build host also needs makepkg, tar, xz, python3, PyInstaller, and the project Python build dependencies.

FreeBSD:

sudo pkg install ncurses libyaml xclip xsel

macOS:

brew install ncurses libyaml

Windows:

Prebuilt installer and portable .exe artifacts do not require a separate Python installation. Windows Terminal or another modern terminal is recommended, PowerShell is used for checksum examples, and Git is optional for repository workflows. The official installer normally bundles the required runtime components; install the Visual C++ runtime only if a release note says that a specific artifact requires it.

For source/development builds on Windows, install Python 3.11+, Git, PowerShell 7, NSIS for installer builds, and Visual Studio Build Tools only when native dependency or build-tool compilation is required.

Option A: Pre-built Packages (Recommended)

Download from GitHub Releases when available:

• Linux: .deb (Debian/Ubuntu), .rpm (Fedora/RHEL and SUSE/openSUSE), Arch pkg.tar.zst, Slackware .txz, AppImage

• FreeBSD: .pkg

• macOS: .dmg (install notes)

• Windows: .exe installer or portable executable (install notes)

• Release metadata: CycloneDX SBOM and SHA256 sidecars for release artifacts

Option B: PyPI (Python Package Index)

sudo apt update
sudo apt install pipx
pipx ensurepath
pipx install ecli-editor
ecli

Import and launch names are unchanged:

import ecli

ecli

For isolated development or testing:

python3 -m venv ~/.local/ecli-env
source ~/.local/ecli-env/bin/activate
pip install ecli-editor
ecli

On Debian 13 and newer Ubuntu releases, direct system-level pip install may fail with externally-managed-environment. Use pipx, a virtual environment, or the official .deb package from GitHub Releases when available.

Avoid pip install --break-system-packages ecli-editor unless you fully understand the apt package-management consequences.

Requires Python 3.11+ and system dependencies listed above. Native packages may install launcher integration automatically; pip/pipx installs use ecli-install-desktop-entry for explicit Linux desktop integration.

Use release artifacts from GitHub Releases when available. Exact artifact names include version and architecture.

# Debian / Ubuntu
sudo apt install ./ecli_<version>_linux_x86_64.deb
# Fedora / RHEL
sudo dnf install ./ecli_<version>_linux_x86_64.rpm
# SUSE / openSUSE
sudo zypper install ./ecli_<version>_opensuse_x86_64.rpm
# Arch Linux release artifact
sudo pacman -U ./ecli_<version>_arch_x86_64.pkg.tar.zst
# Arch Linux local PKGBUILD
cd packaging/arch
makepkg -si
# Slackware
sudo installpkg ecli_<version>_slackware_x86_64.txz
sudo upgradepkg ecli_<version>_slackware_x86_64.txz
sudo removepkg ecli
# NixOS / Nix
nix run .
nix build .
nix profile install .
# FreeBSD
sudo pkg add ./ecli_<version>_freebsd_x86_64.pkg
# AppImage
chmod +x ./ecli_<version>_linux_x86_64.AppImage
./ecli_<version>_linux_x86_64.AppImage

The Arch package is named ecli-editor and installs the ecli command. Raw makepkg output may use ecli-editor-<version>-1-<arch>.pkg.tar.zst;

the ECLI release script normalizes it to ecli_<version>_arch_<arch>.pkg.tar.zst for GitHub Releases. AUR publishing is not implemented by this repository yet. If openSUSE dependencies are missing, use zypper to resolve them from configured repositories.

• Python 3.11+

• Git

• System dependencies (see above)

• uv package manager (optional, for faster builds)

# Clone the repository
git clone https://github.com/SSobol77/ecli.git
cd ecli
# Install dependencies
make install
# Run from source
make run
# Build packages for distribution
make help # See all available build targets

Taskfile.yml is available as an optional developer convenience wrapper for common local commands such as task help, task validate, and task validate-packaging. Makefile remains the authoritative build/release contract; CI and release gates continue to rely on the existing canonical command surfaces.

ECLI features a comprehensive multi-platform build system. For detailed information:

• Build from Source: Read docs/contributor/build-from-source.md

• Packaging Flows: See docs/release/packaging-flows.md

# Display all available build targets
make help
task help # Optional wrapper; delegates to make help
# Check system capabilities and available tools
make sysinfo
# Build for your platform
make package-linux # Linux package targets supported by the local toolchain
make package-pypi # Python wheel + source distribution
make package-macos # macOS DMG
make package-windows # Windows portable EXE + installer
make package-freebsd # FreeBSD package
# Maintainer-owned guarded release/publish flow
make publish-all

ecli [options] [file]

Master ECLI with these essential keyboard shortcuts. Press F1 anytime inside the editor to open the help screen.

The right side of the editor hosts workflow panels. The v0.2.4 release keeps service panels read-only or preview-only: System Doctor does not mutate host state, Command Plan previews do not execute, the Services panel reports composition status, F4 opens the Diagnostics/Linter panel, F11 opens or focuses the PySH Console Panel, and F12 switches focus between the editor and panels.

The default CLI path still launches the editor:

python3 -m ecli
python3 -m ecli pyproject.toml

The explicit service flags provide read-only inspection without bypassing the TUI model:

python3 -m ecli --services
python3 -m ecli --doctor
python3 -m ecli --plan-preview

Use --json for deterministic JSON output where supported. These commands are inspection and preview surfaces only; they do not execute plans, run privileged commands, install packages, start VMLab, or apply remediation.

AI features require user-provided provider credentials. API keys belong in:

~/.config/ecli/.env

Provider selection belongs in config.toml, not in .env. If a selected provider key is missing, the AI panel reports a normal configuration message instead of a Python traceback.

For comprehensive keybindings and usage guide, see Getting Started.

Complete documentation is organized by audience:

• Installation Guide - Detailed setup instructions

• Build from Source - Build system quick start

• Getting Started - First steps with ECLI

• Development Setup - Development environment

• Architecture Overview - System design

• Packaging Flows - Release packaging overview

• Build from Source - Local build commands

• Contributor Guide - Contributing to ECLI

• Supported Platforms - Platform matrix

• Configuration Guide - Configuration options

• Deployment Guide - Production deployment

• API Documentation - Plugin development

• Architecture Details - System internals

• Release Process - Release management

• Quality Standards - Testing and quality gates

ECLI v0.2.4 keeps the existing editor/TUI behavior, Services Foundation infrastructure, and Panel Console Stabilization baseline, then adds the Extensions Foundation, TextMate-backed syntax rendering, and F4 Diagnostics/Linter architecture:

• Core Editor: curses-based terminal editor with async task integration

• Right-Side Panels: Help, Diagnostics/Lint, AI Code Assistant, System Doctor, Git, File Manager, Services, and Command Plan previews

• Extensions Layer: curated data-only language and theme assets under src/ecli/extensions/, consumed through deterministic ECLI adapter code

• Syntax Service: extension-backed language detection, TextMate grammar catalog lookup, scope rendering, and multiline comment/string protection

• Theme Registry: extension-backed theme registry and bridge with numbered theme selection and migration compatibility

• F4 Diagnostics/Linter: normalized diagnostics service, provider registry, Ruff reference provider, and linter microservice metadata under src/ecli/extensions/linters/

• F4 Provisioning Contracts: OS/artifact-aware linter provisioning evidence gates, Linux official distro evidence, and exact 21-artifact coverage for release readiness

• PySH Console Panel: F11 opens or focuses an ECLI-owned command console panel backed by PySH subprocess execution

• ConfigService: typed layered configuration loading

• ProjectService: deterministic project discovery and path normalization

• CommandPlanService: draft command-plan models and preview/export behavior

• BuiltInPolicyEngine: deterministic built-in policy evaluation rules

• AuditLogService: append-only JSONL audit records with mandatory redaction

• PrivilegedActionService: refusal-only/dry-run-only skeleton for future elevated operations

• SystemDoctor: read-only diagnostic skeleton with draft remediation-plan generation

• ServiceRegistry: explicit composition root without global service-locator state

Safety boundaries for v0.2.4:

• SystemDoctor is read-only.

• CommandPlan output is draft/preview-only.

• PrivilegedActionService refuses real execution in this release.

• Service panels are visible in the UI but do not execute remediation.

• Imported extension assets are data-only; ECLI does not execute VS Code extension runtime code.

• F4 provisioning evidence gates are release/packaging contracts and do not change F4 panel UI behavior.

• Full PTY terminal emulation, VT parsing, xterm behavior, and raw interactive PySH inside curses are not included.

• PySH is used as a command execution backend only; PySH source migration and monorepo conversion are not included.

• VMLab runtime behavior, QEMU runtime scope, and QMP runtime scope are not included in v0.2.4.

For detailed architecture information, see Architecture Overview.

We welcome contributions! Here's how to get started:

1. Fork the repository

2. Clone your fork: git clone https://github.com/YOUR_USERNAME/ecli.git

3. Create a feature branch: git checkout -b feature/your-feature

4. Make your changes

5. Test your changes: make clean && make install && make run

6. Commit with clear messages

7. Push to your fork

8. Open a Pull Request

For detailed contribution guidelines, see CONTRIBUTING.

# Clone and setup
git clone https://github.com/SSobol77/ecli.git
cd ecli
# Install dev dependencies
make install
# Run tests
python -m pytest
# Run linter
ruff check src/
# Format code
black src/

ecli/
├── src/ecli/ # Main source code
│ ├── core/ # Core editor functionality
│ ├── ui/ # Terminal UI components
│ ├── integrations/ # AI, Git, LSP integrations
│ └── utils/ # Utilities and helpers
├── docs/ # Documentation
├── tests/ # Test suite
├── scripts/ # Build and utility scripts
└── Makefile # Multi-platform build system

Found a bug? Please help us by opening an issue on GitHub:

• Issue Tracker

• Include: OS, Python version, ECLI version, and reproduction steps

• Check Known Issues first

• OS: Linux, macOS, FreeBSD, or Windows

• Python: 3.11 or higher

• Terminal: Supports 256 colors and UTF-8

• TextMate syntax highlighting (default): installed automatically via the python-textmate dependency, which pulls onigurumacffi (the Oniguruma regex engine). Binary wheels cover Linux, macOS, and Windows. On source-build platforms (e.g. FreeBSD) install the Oniguruma development headers (devel/oniguruma). If unavailable, ECLI falls back to the built-in legacy highlighter automatically ([extensions].syntax_engine = "legacy").

• Ubuntu 20.04 LTS and newer

• Debian 11 and newer

• Fedora 36 and newer

• RHEL/CentOS/Rocky 8.0 and newer

• Arch Linux (current)

• FreeBSD 14.0 and newer

• macOS 12 and newer

• Windows 10/11

See Supported Platforms for detailed compatibility matrix.

ECLI is licensed under the GNU General Public License version 2 only (GPL-2.0-only).

See the LICENSE file for the full license text.

• Website: https://www.ecli.io

• GitHub: https://github.com/SSobol77/ecli

• Issues: https://github.com/SSobol77/ecli/issues

• Discussions: https://github.com/SSobol77/ecli/discussions

• PyPI: https://pypi.org/project/ecli-editor/

• Releases: https://github.com/SSobol77/ecli/releases

• Documentation: Read Build from Source and Packaging Flows

• Community: GitHub Discussions

• Bugs: GitHub Issues

• Development: See Contributing

For planned features and current development status, see Roadmap.

Made with ❤️ by the ECLI community
⭐ Star us on GitHub!